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"
15 #include "llvm/Support/BinaryStreamArray.h"
16 #include "llvm/Support/BinaryStreamRef.h"
17 #include "llvm/Support/ConvertUTF.h"
18 #include "llvm/Support/Endian.h"
19 #include "llvm/Support/Error.h"
20 #include "llvm/Support/type_traits.h"
21 
22 #include <string>
23 #include <type_traits>
24 
25 namespace llvm {
26 
27 /// 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.
32 class BinaryStreamReader {
33 public:
34   BinaryStreamReader() = default;
35   explicit BinaryStreamReader(BinaryStreamRef Ref);
36   explicit BinaryStreamReader(BinaryStream &Stream);
37   explicit BinaryStreamReader(ArrayRef<uint8_t> Data,
38                               llvm::support::endianness Endian);
39   explicit BinaryStreamReader(StringRef Data, llvm::support::endianness Endian);
40 
BinaryStreamReader(const BinaryStreamReader & Other)41   BinaryStreamReader(const BinaryStreamReader &Other)
42       : Stream(Other.Stream), Offset(Other.Offset) {}
43 
44   BinaryStreamReader &operator=(const BinaryStreamReader &Other) {
45     Stream = Other.Stream;
46     Offset = Other.Offset;
47     return *this;
48   }
49 
~BinaryStreamReader()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.
58   Error readLongestContiguousChunk(ArrayRef<uint8_t> &Buffer);
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.
67   Error readBytes(ArrayRef<uint8_t> &Buffer, uint32_t Size);
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.
readInteger(T & Dest)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.
readEnum(T & Dest)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.
113   Error readWideString(ArrayRef<UTF16> &Dest);
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.
129   Error readStreamRef(BinaryStreamRef &Ref);
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.
138   Error readStreamRef(BinaryStreamRef &Ref, uint32_t Length);
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.
147   Error readSubstream(BinarySubstreamRef &Stream, uint32_t Size);
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.
readObject(const T * & Dest)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>
readArray(ArrayRef<T> & Array,uint32_t NumElements)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>(
185           stream_error_code::invalid_array_size);
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>
readArray(VarStreamArray<T,U> & Array,uint32_t Size)206   Error readArray(VarStreamArray<T, U> &Array, uint32_t Size) {
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>
readArray(FixedStreamArray<T> & Array,uint32_t NumItems)223   Error readArray(FixedStreamArray<T> &Array, uint32_t NumItems) {
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>(
231           stream_error_code::invalid_array_size);
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 
empty()241   bool empty() const { return bytesRemaining() == 0; }
setOffset(uint32_t Off)242   void setOffset(uint32_t Off) { Offset = Off; }
getOffset()243   uint32_t getOffset() const { return Offset; }
getLength()244   uint32_t getLength() const { return Stream.getLength(); }
bytesRemaining()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 
259   Error padToAlignment(uint32_t Align);
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
271