1//===- BinaryStreamReader.h - Reads objects from a binary stream *- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#ifndef LLVM_SUPPORT_BINARYSTREAMREADER_H
10#define LLVM_SUPPORT_BINARYSTREAMREADER_H
11
12#include "llvm/ADT/ArrayRef.h"
13#include "llvm/ADT/STLExtras.h"
14#include "llvm/ADT/StringRef.h"
15#include "llvm/Support/Alignment.h"
16#include "llvm/Support/BinaryStreamArray.h"
17#include "llvm/Support/BinaryStreamRef.h"
18#include "llvm/Support/ConvertUTF.h"
19#include "llvm/Support/Endian.h"
20#include "llvm/Support/Error.h"
21#include "llvm/Support/type_traits.h"
22#include <type_traits>
23
24namespace llvm {
25
26/// Provides read only access to a subclass of `BinaryStream`. Provides
27/// bounds checking and helpers for writing certain common data types such as
28/// null-terminated strings, integers in various flavors of endianness, etc.
29/// Can be subclassed to provide reading of custom datatypes, although no
30/// are overridable.
31class BinaryStreamReader {
32public:
33 BinaryStreamReader() = default;
34 explicit BinaryStreamReader(BinaryStreamRef Ref);
35 explicit BinaryStreamReader(BinaryStream &Stream);
36 explicit BinaryStreamReader(ArrayRef<uint8_t> Data,
37 llvm::support::endianness Endian);
38 explicit BinaryStreamReader(StringRef Data, llvm::support::endianness Endian);
39
40 BinaryStreamReader(const BinaryStreamReader &Other)
41 : Stream(Other.Stream), Offset(Other.Offset) {}
42
43 BinaryStreamReader &operator=(const BinaryStreamReader &Other) {
44 Stream = Other.Stream;
45 Offset = Other.Offset;
46 return *this;
47 }
48
49 virtual ~BinaryStreamReader() {}
50
51 /// Read as much as possible from the underlying string at the current offset
52 /// without invoking a copy, and set \p Buffer to the resulting data slice.
53 /// Updates the stream's offset to point after the newly read data.
54 ///
55 /// \returns a success error code if the data was successfully read, otherwise
56 /// returns an appropriate error code.
57 Error readLongestContiguousChunk(ArrayRef<uint8_t> &Buffer);
58
59 /// Read \p Size bytes from the underlying stream at the current offset and
60 /// and set \p Buffer to the resulting data slice. Whether a copy occurs
61 /// depends on the implementation of the underlying stream. Updates the
62 /// stream's offset to point after the newly read data.
63 ///
64 /// \returns a success error code if the data was successfully read, otherwise
65 /// returns an appropriate error code.
66 Error readBytes(ArrayRef<uint8_t> &Buffer, uint32_t Size);
67
68 /// Read an integer of the specified endianness into \p Dest and update the
69 /// stream's offset. The data is always copied from the stream's underlying
70 /// buffer into \p Dest. Updates the stream's offset to point after the newly
71 /// read data.
72 ///
73 /// \returns a success error code if the data was successfully read, otherwise
74 /// returns an appropriate error code.
75 template <typename T> Error readInteger(T &Dest) {
76 static_assert(std::is_integral<T>::value,
77 "Cannot call readInteger with non-integral value!");
78
79 ArrayRef<uint8_t> Bytes;
80 if (auto EC = readBytes(Bytes, sizeof(T)))
81 return EC;
82
83 Dest = llvm::support::endian::read<T, llvm::support::unaligned>(
84 Bytes.data(), Stream.getEndian());
85 return Error::success();
86 }
87
88 /// Similar to readInteger.
89 template <typename T> Error readEnum(T &Dest) {
90 static_assert(std::is_enum<T>::value,
91 "Cannot call readEnum with non-enum value!");
92 std::underlying_type_t<T> N;
93 if (auto EC = readInteger(N))
94 return EC;
95 Dest = static_cast<T>(N);
96 return Error::success();
97 }
98
99 /// Read an unsigned LEB128 encoded value.
100 ///
101 /// \returns a success error code if the data was successfully read, otherwise
102 /// returns an appropriate error code.
103 Error readULEB128(uint64_t &Dest);
104
105 /// Read a signed LEB128 encoded value.
106 ///
107 /// \returns a success error code if the data was successfully read, otherwise
108 /// returns an appropriate error code.
109 Error readSLEB128(int64_t &Dest);
110
111 /// Read a null terminated string from \p Dest. Whether a copy occurs depends
112 /// on the implementation of the underlying stream. Updates the stream's
113 /// offset to point after the newly read data.
114 ///
115 /// \returns a success error code if the data was successfully read, otherwise
116 /// returns an appropriate error code.
117 Error readCString(StringRef &Dest);
118
119 /// Similar to readCString, however read a null-terminated UTF16 string
120 /// instead.
121 ///
122 /// \returns a success error code if the data was successfully read, otherwise
123 /// returns an appropriate error code.
124 Error readWideString(ArrayRef<UTF16> &Dest);
125
126 /// Read a \p Length byte string into \p Dest. Whether a copy occurs depends
127 /// on the implementation of the underlying stream. Updates the stream's
128 /// offset to point after the newly read data.
129 ///
130 /// \returns a success error code if the data was successfully read, otherwise
131 /// returns an appropriate error code.
132 Error readFixedString(StringRef &Dest, uint32_t Length);
133
134 /// Read the entire remainder of the underlying stream into \p Ref. This is
135 /// equivalent to calling getUnderlyingStream().slice(Offset). Updates the
136 /// stream's offset to point to the end of the stream. Never causes a copy.
137 ///
138 /// \returns a success error code if the data was successfully read, otherwise
139 /// returns an appropriate error code.
140 Error readStreamRef(BinaryStreamRef &Ref);
141
142 /// Read \p Length bytes from the underlying stream into \p Ref. This is
143 /// equivalent to calling getUnderlyingStream().slice(Offset, Length).
144 /// Updates the stream's offset to point after the newly read object. Never
145 /// causes a copy.
146 ///
147 /// \returns a success error code if the data was successfully read, otherwise
148 /// returns an appropriate error code.
149 Error readStreamRef(BinaryStreamRef &Ref, uint32_t Length);
150
151 /// Read \p Length bytes from the underlying stream into \p Ref. This is
152 /// equivalent to calling getUnderlyingStream().slice(Offset, Length).
153 /// Updates the stream's offset to point after the newly read object. Never
154 /// causes a copy.
155 ///
156 /// \returns a success error code if the data was successfully read, otherwise
157 /// returns an appropriate error code.
158 Error readSubstream(BinarySubstreamRef &Ref, uint32_t Length);
159
160 /// Get a pointer to an object of type T from the underlying stream, as if by
161 /// memcpy, and store the result into \p Dest. It is up to the caller to
162 /// ensure that objects of type T can be safely treated in this manner.
163 /// Updates the stream's offset to point after the newly read object. Whether
164 /// a copy occurs depends upon the implementation of the underlying
165 /// stream.
166 ///
167 /// \returns a success error code if the data was successfully read, otherwise
168 /// returns an appropriate error code.
169 template <typename T> Error readObject(const T *&Dest) {
170 ArrayRef<uint8_t> Buffer;
171 if (auto EC = readBytes(Buffer, sizeof(T)))
172 return EC;
173 Dest = reinterpret_cast<const T *>(Buffer.data());
174 return Error::success();
175 }
176
177 /// Get a reference to a \p NumElements element array of objects of type T
178 /// from the underlying stream as if by memcpy, and store the resulting array
179 /// slice into \p array. It is up to the caller to ensure that objects of
180 /// type T can be safely treated in this manner. Updates the stream's offset
181 /// to point after the newly read object. Whether a copy occurs depends upon
182 /// the implementation of the underlying stream.
183 ///
184 /// \returns a success error code if the data was successfully read, otherwise
185 /// returns an appropriate error code.
186 template <typename T>
187 Error readArray(ArrayRef<T> &Array, uint32_t NumElements) {
188 ArrayRef<uint8_t> Bytes;
189 if (NumElements == 0) {
190 Array = ArrayRef<T>();
191 return Error::success();
192 }
193
194 if (NumElements > UINT32_MAX / sizeof(T))
195 return make_error<BinaryStreamError>(
196 stream_error_code::invalid_array_size);
197
198 if (auto EC = readBytes(Bytes, NumElements * sizeof(T)))
199 return EC;
200
201 assert(isAddrAligned(Align::Of<T>(), Bytes.data()) &&
202 "Reading at invalid alignment!");
203
204 Array = ArrayRef<T>(reinterpret_cast<const T *>(Bytes.data()), NumElements);
205 return Error::success();
206 }
207
208 /// Read a VarStreamArray of size \p Size bytes and store the result into
209 /// \p Array. Updates the stream's offset to point after the newly read
210 /// array. Never causes a copy (although iterating the elements of the
211 /// VarStreamArray may, depending upon the implementation of the underlying
212 /// stream).
213 ///
214 /// \returns a success error code if the data was successfully read, otherwise
215 /// returns an appropriate error code.
216 template <typename T, typename U>
217 Error readArray(VarStreamArray<T, U> &Array, uint32_t Size,
218 uint32_t Skew = 0) {
219 BinaryStreamRef S;
220 if (auto EC = readStreamRef(S, Size))
221 return EC;
222 Array.setUnderlyingStream(S, Skew);
223 return Error::success();
224 }
225
226 /// Read a FixedStreamArray of \p NumItems elements and store the result into
227 /// \p Array. Updates the stream's offset to point after the newly read
228 /// array. Never causes a copy (although iterating the elements of the
229 /// FixedStreamArray may, depending upon the implementation of the underlying
230 /// stream).
231 ///
232 /// \returns a success error code if the data was successfully read, otherwise
233 /// returns an appropriate error code.
234 template <typename T>
235 Error readArray(FixedStreamArray<T> &Array, uint32_t NumItems) {
236 if (NumItems == 0) {
237 Array = FixedStreamArray<T>();
238 return Error::success();
239 }
240
241 if (NumItems > UINT32_MAX / sizeof(T))
242 return make_error<BinaryStreamError>(
243 stream_error_code::invalid_array_size);
244
245 BinaryStreamRef View;
246 if (auto EC = readStreamRef(View, NumItems * sizeof(T)))
247 return EC;
248
249 Array = FixedStreamArray<T>(View);
250 return Error::success();
251 }
252
253 bool empty() const { return bytesRemaining() == 0; }
254 void setOffset(uint32_t Off) { Offset = Off; }
255 uint32_t getOffset() const { return Offset; }
256 uint32_t getLength() const { return Stream.getLength(); }
257 uint32_t bytesRemaining() const { return getLength() - getOffset(); }
258
259 /// Advance the stream's offset by \p Amount bytes.
260 ///
261 /// \returns a success error code if at least \p Amount bytes remain in the
262 /// stream, otherwise returns an appropriate error code.
263 Error skip(uint32_t Amount);
264
265 /// Examine the next byte of the underlying stream without advancing the
266 /// stream's offset. If the stream is empty the behavior is undefined.
267 ///
268 /// \returns the next byte in the stream.
269 uint8_t peek() const;
270
271 Error padToAlignment(uint32_t Align);
272
273 std::pair<BinaryStreamReader, BinaryStreamReader>
274 split(uint32_t Offset) const;
275
276private:
277 BinaryStreamRef Stream;
278 uint32_t Offset = 0;
279};
280} // namespace llvm
281
282#endif // LLVM_SUPPORT_BINARYSTREAMREADER_H
283