LLVM  6.0.0svn
BinaryStreamReader.h
Go to the documentation of this file.
1 //===- BinaryStreamReader.h - Reads objects from a binary 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_BINARYSTREAMREADER_H
11 #define LLVM_SUPPORT_BINARYSTREAMREADER_H
12 
13 #include "llvm/ADT/ArrayRef.h"
14 #include "llvm/ADT/STLExtras.h"
18 #include "llvm/Support/Endian.h"
19 #include "llvm/Support/Error.h"
21 
22 #include <string>
23 #include <type_traits>
24 
25 namespace llvm {
26 
27 /// \brief Provides read only access to a subclass of `BinaryStream`. Provides
28 /// bounds checking and helpers for writing certain common data types such as
29 /// null-terminated strings, integers in various flavors of endianness, etc.
30 /// Can be subclassed to provide reading of custom datatypes, although no
31 /// are overridable.
33 public:
34  BinaryStreamReader() = default;
35  explicit BinaryStreamReader(BinaryStreamRef Ref);
36  explicit BinaryStreamReader(BinaryStream &Stream);
40 
42  : Stream(Other.Stream), Offset(Other.Offset) {}
43 
45  Stream = Other.Stream;
46  Offset = Other.Offset;
47  return *this;
48  }
49 
50  virtual ~BinaryStreamReader() {}
51 
52  /// Read as much as possible from the underlying string at the current offset
53  /// without invoking a copy, and set \p Buffer to the resulting data slice.
54  /// Updates the stream's offset to point after the newly read data.
55  ///
56  /// \returns a success error code if the data was successfully read, otherwise
57  /// returns an appropriate error code.
59 
60  /// Read \p Size bytes from the underlying stream at the current offset and
61  /// and set \p Buffer to the resulting data slice. Whether a copy occurs
62  /// depends on the implementation of the underlying stream. Updates the
63  /// stream's offset to point after the newly read data.
64  ///
65  /// \returns a success error code if the data was successfully read, otherwise
66  /// returns an appropriate error code.
68 
69  /// Read an integer of the specified endianness into \p Dest and update the
70  /// stream's offset. The data is always copied from the stream's underlying
71  /// buffer into \p Dest. Updates the stream's offset to point after the newly
72  /// read data.
73  ///
74  /// \returns a success error code if the data was successfully read, otherwise
75  /// returns an appropriate error code.
76  template <typename T> Error readInteger(T &Dest) {
77  static_assert(std::is_integral<T>::value,
78  "Cannot call readInteger with non-integral value!");
79 
80  ArrayRef<uint8_t> Bytes;
81  if (auto EC = readBytes(Bytes, sizeof(T)))
82  return EC;
83 
84  Dest = llvm::support::endian::read<T, llvm::support::unaligned>(
85  Bytes.data(), Stream.getEndian());
86  return Error::success();
87  }
88 
89  /// Similar to readInteger.
90  template <typename T> Error readEnum(T &Dest) {
91  static_assert(std::is_enum<T>::value,
92  "Cannot call readEnum with non-enum value!");
93  typename std::underlying_type<T>::type N;
94  if (auto EC = readInteger(N))
95  return EC;
96  Dest = static_cast<T>(N);
97  return Error::success();
98  }
99 
100  /// Read a null terminated string from \p Dest. Whether a copy occurs depends
101  /// on the implementation of the underlying stream. Updates the stream's
102  /// offset to point after the newly read data.
103  ///
104  /// \returns a success error code if the data was successfully read, otherwise
105  /// returns an appropriate error code.
106  Error readCString(StringRef &Dest);
107 
108  /// Similar to readCString, however read a null-terminated UTF16 string
109  /// instead.
110  ///
111  /// \returns a success error code if the data was successfully read, otherwise
112  /// returns an appropriate error code.
114 
115  /// Read a \p Length byte string into \p Dest. Whether a copy occurs depends
116  /// on the implementation of the underlying stream. Updates the stream's
117  /// offset to point after the newly read data.
118  ///
119  /// \returns a success error code if the data was successfully read, otherwise
120  /// returns an appropriate error code.
121  Error readFixedString(StringRef &Dest, uint32_t Length);
122 
123  /// Read the entire remainder of the underlying stream into \p Ref. This is
124  /// equivalent to calling getUnderlyingStream().slice(Offset). Updates the
125  /// stream's offset to point to the end of the stream. Never causes a copy.
126  ///
127  /// \returns a success error code if the data was successfully read, otherwise
128  /// returns an appropriate error code.
130 
131  /// Read \p Length bytes from the underlying stream into \p Ref. This is
132  /// equivalent to calling getUnderlyingStream().slice(Offset, Length).
133  /// Updates the stream's offset to point after the newly read object. Never
134  /// causes a copy.
135  ///
136  /// \returns a success error code if the data was successfully read, otherwise
137  /// returns an appropriate error code.
139 
140  /// Read \p Length bytes from the underlying stream into \p Stream. This is
141  /// equivalent to calling getUnderlyingStream().slice(Offset, Length).
142  /// Updates the stream's offset to point after the newly read object. Never
143  /// causes a copy.
144  ///
145  /// \returns a success error code if the data was successfully read, otherwise
146  /// returns an appropriate error code.
148 
149  /// Get a pointer to an object of type T from the underlying stream, as if by
150  /// memcpy, and store the result into \p Dest. It is up to the caller to
151  /// ensure that objects of type T can be safely treated in this manner.
152  /// Updates the stream's offset to point after the newly read object. Whether
153  /// a copy occurs depends upon the implementation of the underlying
154  /// stream.
155  ///
156  /// \returns a success error code if the data was successfully read, otherwise
157  /// returns an appropriate error code.
158  template <typename T> Error readObject(const T *&Dest) {
159  ArrayRef<uint8_t> Buffer;
160  if (auto EC = readBytes(Buffer, sizeof(T)))
161  return EC;
162  Dest = reinterpret_cast<const T *>(Buffer.data());
163  return Error::success();
164  }
165 
166  /// Get a reference to a \p NumElements element array of objects of type T
167  /// from the underlying stream as if by memcpy, and store the resulting array
168  /// slice into \p array. It is up to the caller to ensure that objects of
169  /// type T can be safely treated in this manner. Updates the stream's offset
170  /// to point after the newly read object. Whether a copy occurs depends upon
171  /// the implementation of the underlying stream.
172  ///
173  /// \returns a success error code if the data was successfully read, otherwise
174  /// returns an appropriate error code.
175  template <typename T>
176  Error readArray(ArrayRef<T> &Array, uint32_t NumElements) {
177  ArrayRef<uint8_t> Bytes;
178  if (NumElements == 0) {
179  Array = ArrayRef<T>();
180  return Error::success();
181  }
182 
183  if (NumElements > UINT32_MAX / sizeof(T))
184  return make_error<BinaryStreamError>(
186 
187  if (auto EC = readBytes(Bytes, NumElements * sizeof(T)))
188  return EC;
189 
190  assert(alignmentAdjustment(Bytes.data(), alignof(T)) == 0 &&
191  "Reading at invalid alignment!");
192 
193  Array = ArrayRef<T>(reinterpret_cast<const T *>(Bytes.data()), NumElements);
194  return Error::success();
195  }
196 
197  /// Read a VarStreamArray of size \p Size bytes and store the result into
198  /// \p Array. Updates the stream's offset to point after the newly read
199  /// array. Never causes a copy (although iterating the elements of the
200  /// VarStreamArray may, depending upon the implementation of the underlying
201  /// stream).
202  ///
203  /// \returns a success error code if the data was successfully read, otherwise
204  /// returns an appropriate error code.
205  template <typename T, typename U>
207  BinaryStreamRef S;
208  if (auto EC = readStreamRef(S, Size))
209  return EC;
210  Array.setUnderlyingStream(S);
211  return Error::success();
212  }
213 
214  /// Read a FixedStreamArray of \p NumItems elements and store the result into
215  /// \p Array. Updates the stream's offset to point after the newly read
216  /// array. Never causes a copy (although iterating the elements of the
217  /// FixedStreamArray may, depending upon the implementation of the underlying
218  /// stream).
219  ///
220  /// \returns a success error code if the data was successfully read, otherwise
221  /// returns an appropriate error code.
222  template <typename T>
224  if (NumItems == 0) {
225  Array = FixedStreamArray<T>();
226  return Error::success();
227  }
228 
229  if (NumItems > UINT32_MAX / sizeof(T))
230  return make_error<BinaryStreamError>(
232 
233  BinaryStreamRef View;
234  if (auto EC = readStreamRef(View, NumItems * sizeof(T)))
235  return EC;
236 
237  Array = FixedStreamArray<T>(View);
238  return Error::success();
239  }
240 
241  bool empty() const { return bytesRemaining() == 0; }
242  void setOffset(uint32_t Off) { Offset = Off; }
243  uint32_t getOffset() const { return Offset; }
244  uint32_t getLength() const { return Stream.getLength(); }
245  uint32_t bytesRemaining() const { return getLength() - getOffset(); }
246 
247  /// Advance the stream's offset by \p Amount bytes.
248  ///
249  /// \returns a success error code if at least \p Amount bytes remain in the
250  /// stream, otherwise returns an appropriate error code.
251  Error skip(uint32_t Amount);
252 
253  /// Examine the next byte of the underlying stream without advancing the
254  /// stream's offset. If the stream is empty the behavior is undefined.
255  ///
256  /// \returns the next byte in the stream.
257  uint8_t peek() const;
258 
260 
261  std::pair<BinaryStreamReader, BinaryStreamReader>
262  split(uint32_t Offset) const;
263 
264 private:
265  BinaryStreamRef Stream;
266  uint32_t Offset = 0;
267 };
268 } // namespace llvm
269 
270 #endif // LLVM_SUPPORT_BINARYSTREAMREADER_H
constexpr char Align[]
Key for Kernel::Arg::Metadata::mAlign.
Error padToAlignment(uint32_t Align)
Error readArray(VarStreamArray< T, U > &Array, uint32_t Size)
Read a VarStreamArray of size Size bytes and store the result into Array.
Error readSubstream(BinarySubstreamRef &Stream, uint32_t Size)
Read Length bytes from the underlying stream into Stream.
Compute iterated dominance frontiers using a linear time algorithm.
Definition: AllocatorList.h:24
void setUnderlyingStream(BinaryStreamRef S)
Error readInteger(T &Dest)
Read an integer of the specified endianness into Dest and update the stream&#39;s offset.
Error readWideString(ArrayRef< UTF16 > &Dest)
Similar to readCString, however read a null-terminated UTF16 string instead.
Error readObject(const T *&Dest)
Get a pointer to an object of type T from the underlying stream, as if by memcpy, and store the resul...
uint8_t peek() const
Examine the next byte of the underlying stream without advancing the stream&#39;s offset.
FixedStreamArray is similar to VarStreamArray, except with each record having a fixed-length.
BinaryStreamReader & operator=(const BinaryStreamReader &Other)
Error readCString(StringRef &Dest)
Read a null terminated string from Dest.
std::pair< BinaryStreamReader, BinaryStreamReader > split(uint32_t Offset) const
Error readFixedString(StringRef &Dest, uint32_t Length)
Read a Length byte string into Dest.
#define T
virtual llvm::support::endianness getEndian() const =0
Error readArray(FixedStreamArray< T > &Array, uint32_t NumItems)
Read a FixedStreamArray of NumItems elements and store the result into Array.
An interface for accessing data in a stream-like format, but which discourages copying.
Definition: BinaryStream.h:28
size_t alignmentAdjustment(const void *Ptr, size_t Alignment)
Returns the necessary adjustment for aligning Ptr to Alignment bytes, rounding up.
Definition: MathExtras.h:626
BinaryStreamReader(const BinaryStreamReader &Other)
const T * data() const
Definition: ArrayRef.h:146
void setOffset(uint32_t Off)
static ErrorSuccess success()
Create a success value.
Definition: Error.h:313
BinaryStreamRef is to BinaryStream what ArrayRef is to an Array.
Error readBytes(ArrayRef< uint8_t > &Buffer, uint32_t Size)
Read Size bytes from the underlying stream at the current offset and and set Buffer to the resulting ...
#define N
Error readStreamRef(BinaryStreamRef &Ref)
Read the entire remainder of the underlying stream into Ref.
Error skip(uint32_t Amount)
Advance the stream&#39;s offset by Amount bytes.
uint32_t bytesRemaining() const
assert(ImpDefSCC.getReg()==AMDGPU::SCC &&ImpDefSCC.isDef())
constexpr char Size[]
Key for Kernel::Arg::Metadata::mSize.
Lightweight error class with error context and mandatory checking.
Definition: Error.h:156
Provides read only access to a subclass of BinaryStream.
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:49
Error readEnum(T &Dest)
Similar to readInteger.
Error readLongestContiguousChunk(ArrayRef< uint8_t > &Buffer)
Read as much as possible from the underlying string at the current offset without invoking a copy...
Error readArray(ArrayRef< T > &Array, uint32_t NumElements)
Get a reference to a NumElements element array of objects of type T from the underlying stream as if ...