LLVM  14.0.0git
BinaryStreamWriter.h
Go to the documentation of this file.
1 //===- BinaryStreamWriter.h - Writes objects to a BinaryStream ---*- 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_BINARYSTREAMWRITER_H
10 #define LLVM_SUPPORT_BINARYSTREAMWRITER_H
11 
12 #include "llvm/ADT/ArrayRef.h"
13 #include "llvm/ADT/StringRef.h"
17 #include "llvm/Support/Endian.h"
18 #include "llvm/Support/Error.h"
19 #include <cstdint>
20 #include <type_traits>
21 #include <utility>
22 
23 namespace llvm {
24 
25 /// Provides write only access to a subclass of `WritableBinaryStream`.
26 /// Provides bounds checking and helpers for writing certain common data types
27 /// such as null-terminated strings, integers in various flavors of endianness,
28 /// etc. Can be subclassed to provide reading and writing of custom datatypes,
29 /// although no methods are overridable.
31 public:
32  BinaryStreamWriter() = default;
37 
40 
42  Stream = Other.Stream;
43  Offset = Other.Offset;
44  return *this;
45  }
46 
47  virtual ~BinaryStreamWriter() {}
48 
49  /// Write the bytes specified in \p Buffer to the underlying stream.
50  /// On success, updates the offset so that subsequent writes will occur
51  /// at the next unwritten position.
52  ///
53  /// \returns a success error code if the data was successfully written,
54  /// otherwise returns an appropriate error code.
56 
57  /// Write the integer \p Value to the underlying stream in the
58  /// specified endianness. On success, updates the offset so that
59  /// subsequent writes occur at the next unwritten position.
60  ///
61  /// \returns a success error code if the data was successfully written,
62  /// otherwise returns an appropriate error code.
63  template <typename T> Error writeInteger(T Value) {
64  static_assert(std::is_integral<T>::value,
65  "Cannot call writeInteger with non-integral value!");
66  uint8_t Buffer[sizeof(T)];
67  llvm::support::endian::write<T, llvm::support::unaligned>(
68  Buffer, Value, Stream.getEndian());
69  return writeBytes(Buffer);
70  }
71 
72  /// Similar to writeInteger
73  template <typename T> Error writeEnum(T Num) {
74  static_assert(std::is_enum<T>::value,
75  "Cannot call writeEnum with non-Enum type");
76 
77  using U = std::underlying_type_t<T>;
78  return writeInteger<U>(static_cast<U>(Num));
79  }
80 
81  /// Write the unsigned integer Value to the underlying stream using ULEB128
82  /// encoding.
83  ///
84  /// \returns a success error code if the data was successfully written,
85  /// otherwise returns an appropriate error code.
87 
88  /// Write the unsigned integer Value to the underlying stream using ULEB128
89  /// encoding.
90  ///
91  /// \returns a success error code if the data was successfully written,
92  /// otherwise returns an appropriate error code.
93  Error writeSLEB128(int64_t Value);
94 
95  /// Write the string \p Str to the underlying stream followed by a null
96  /// terminator. On success, updates the offset so that subsequent writes
97  /// occur at the next unwritten position. \p Str need not be null terminated
98  /// on input.
99  ///
100  /// \returns a success error code if the data was successfully written,
101  /// otherwise returns an appropriate error code.
103 
104  /// Write the string \p Str to the underlying stream without a null
105  /// terminator. On success, updates the offset so that subsequent writes
106  /// occur at the next unwritten position.
107  ///
108  /// \returns a success error code if the data was successfully written,
109  /// otherwise returns an appropriate error code.
111 
112  /// Efficiently reads all data from \p Ref, and writes it to this stream.
113  /// This operation will not invoke any copies of the source data, regardless
114  /// of the source stream's implementation.
115  ///
116  /// \returns a success error code if the data was successfully written,
117  /// otherwise returns an appropriate error code.
119 
120  /// Efficiently reads \p Size bytes from \p Ref, and writes it to this stream.
121  /// This operation will not invoke any copies of the source data, regardless
122  /// of the source stream's implementation.
123  ///
124  /// \returns a success error code if the data was successfully written,
125  /// otherwise returns an appropriate error code.
127 
128  /// Writes the object \p Obj to the underlying stream, as if by using memcpy.
129  /// It is up to the caller to ensure that type of \p Obj can be safely copied
130  /// in this fashion, as no checks are made to ensure that this is safe.
131  ///
132  /// \returns a success error code if the data was successfully written,
133  /// otherwise returns an appropriate error code.
134  template <typename T> Error writeObject(const T &Obj) {
135  static_assert(!std::is_pointer<T>::value,
136  "writeObject should not be used with pointers, to write "
137  "the pointed-to value dereference the pointer before calling "
138  "writeObject");
139  return writeBytes(
140  ArrayRef<uint8_t>(reinterpret_cast<const uint8_t *>(&Obj), sizeof(T)));
141  }
142 
143  /// Writes an array of objects of type T to the underlying stream, as if by
144  /// using memcpy. It is up to the caller to ensure that type of \p Obj can
145  /// be safely copied in this fashion, as no checks are made to ensure that
146  /// this is safe.
147  ///
148  /// \returns a success error code if the data was successfully written,
149  /// otherwise returns an appropriate error code.
150  template <typename T> Error writeArray(ArrayRef<T> Array) {
151  if (Array.empty())
152  return Error::success();
153  if (Array.size() > UINT32_MAX / sizeof(T))
154  return make_error<BinaryStreamError>(
156 
157  return writeBytes(
158  ArrayRef<uint8_t>(reinterpret_cast<const uint8_t *>(Array.data()),
159  Array.size() * sizeof(T)));
160  }
161 
162  /// Writes all data from the array \p Array to the underlying stream.
163  ///
164  /// \returns a success error code if the data was successfully written,
165  /// otherwise returns an appropriate error code.
166  template <typename T, typename U>
168  return writeStreamRef(Array.getUnderlyingStream());
169  }
170 
171  /// Writes all elements from the array \p Array to the underlying stream.
172  ///
173  /// \returns a success error code if the data was successfully written,
174  /// otherwise returns an appropriate error code.
175  template <typename T> Error writeArray(FixedStreamArray<T> Array) {
176  return writeStreamRef(Array.getUnderlyingStream());
177  }
178 
179  /// Splits the Writer into two Writers at a given offset.
180  std::pair<BinaryStreamWriter, BinaryStreamWriter> split(uint64_t Off) const;
181 
182  void setOffset(uint64_t Off) { Offset = Off; }
183  uint64_t getOffset() const { return Offset; }
184  uint64_t getLength() const { return Stream.getLength(); }
185  uint64_t bytesRemaining() const { return getLength() - getOffset(); }
187 
188 protected:
191 };
192 
193 } // end namespace llvm
194 
195 #endif // LLVM_SUPPORT_BINARYSTREAMWRITER_H
llvm::Check::Size
@ Size
Definition: FileCheck.h:73
llvm
This is an optimization pass for GlobalISel generic memory operations.
Definition: AllocatorList.h:23
llvm::BinaryStreamWriter::writeInteger
Error writeInteger(T Value)
Write the integer Value to the underlying stream in the specified endianness.
Definition: BinaryStreamWriter.h:63
llvm::BinaryStreamWriter::Stream
WritableBinaryStreamRef Stream
Definition: BinaryStreamWriter.h:189
llvm::BinaryStreamWriter::writeEnum
Error writeEnum(T Num)
Similar to writeInteger.
Definition: BinaryStreamWriter.h:73
llvm::BinaryStreamWriter::writeFixedString
Error writeFixedString(StringRef Str)
Write the string Str to the underlying stream without a null terminator.
Definition: BinaryStreamWriter.cpp:56
StringRef.h
llvm::BinaryStreamWriter
Provides write only access to a subclass of WritableBinaryStream.
Definition: BinaryStreamWriter.h:30
llvm::Error::success
static ErrorSuccess success()
Create a success value.
Definition: Error.h:330
llvm::BinaryStreamWriter::writeStreamRef
Error writeStreamRef(BinaryStreamRef Ref)
Efficiently reads all data from Ref, and writes it to this stream.
Definition: BinaryStreamWriter.cpp:61
Error.h
T
#define T
Definition: Mips16ISelLowering.cpp:341
llvm::BinaryStreamWriter::setOffset
void setOffset(uint64_t Off)
Definition: BinaryStreamWriter.h:182
llvm::BinaryStreamWriter::writeArray
Error writeArray(ArrayRef< T > Array)
Writes an array of objects of type T to the underlying stream, as if by using memcpy.
Definition: BinaryStreamWriter.h:150
llvm::FixedStreamArray
FixedStreamArray is similar to VarStreamArray, except with each record having a fixed-length.
Definition: BinaryStreamArray.h:257
llvm::Data
@ Data
Definition: SIMachineScheduler.h:55
llvm::BinaryStreamWriter::~BinaryStreamWriter
virtual ~BinaryStreamWriter()
Definition: BinaryStreamWriter.h:47
llvm::MutableArrayRef< uint8_t >
llvm::ModRefInfo::Ref
@ Ref
The access may reference the value stored in memory.
llvm::VarStreamArray
Definition: BinaryStreamArray.h:92
llvm::BinaryStreamRefBase::getLength
uint64_t getLength() const
Definition: BinaryStreamRef.h:50
BinaryStreamError.h
llvm::Align
This struct is a compact representation of a valid (non-zero power of two) alignment.
Definition: Alignment.h:39
llvm::BinaryStreamWriter::Offset
uint64_t Offset
Definition: BinaryStreamWriter.h:190
llvm::BinaryStreamWriter::bytesRemaining
uint64_t bytesRemaining() const
Definition: BinaryStreamWriter.h:185
uint64_t
ArrayRef.h
BinaryStreamArray.h
llvm::BinaryStreamWriter::getOffset
uint64_t getOffset() const
Definition: BinaryStreamWriter.h:183
llvm::BinaryStreamWriter::writeSLEB128
Error writeSLEB128(int64_t Value)
Write the unsigned integer Value to the underlying stream using ULEB128 encoding.
Definition: BinaryStreamWriter.cpp:41
llvm::BinaryStreamWriter::writeCString
Error writeCString(StringRef Str)
Write the string Str to the underlying stream followed by a null terminator.
Definition: BinaryStreamWriter.cpp:47
llvm::BinaryStreamWriter::writeArray
Error writeArray(FixedStreamArray< T > Array)
Writes all elements from the array Array to the underlying stream.
Definition: BinaryStreamWriter.h:175
llvm::BinaryStreamWriter::writeULEB128
Error writeULEB128(uint64_t Value)
Write the unsigned integer Value to the underlying stream using ULEB128 encoding.
Definition: BinaryStreamWriter.cpp:35
llvm::ArrayRef< uint8_t >
llvm::BinaryStreamWriter::writeObject
Error writeObject(const T &Obj)
Writes the object Obj to the underlying stream, as if by using memcpy.
Definition: BinaryStreamWriter.h:134
llvm::BinaryStreamWriter::writeBytes
Error writeBytes(ArrayRef< uint8_t > Buffer)
Write the bytes specified in Buffer to the underlying stream.
Definition: BinaryStreamWriter.cpp:28
llvm::StringRef
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:57
BinaryStreamRef.h
uint32_t
llvm::BinaryStreamRefBase::getEndian
llvm::support::endianness getEndian() const
Definition: BinaryStreamRef.h:46
llvm::BinaryStreamWriter::padToAlignment
Error padToAlignment(uint32_t Align)
Definition: BinaryStreamWriter.cpp:95
llvm::Error
Lightweight error class with error context and mandatory checking.
Definition: Error.h:156
llvm::BinaryStreamWriter::writeArray
Error writeArray(VarStreamArray< T, U > Array)
Writes all data from the array Array to the underlying stream.
Definition: BinaryStreamWriter.h:167
llvm::BinaryStreamWriter::split
std::pair< BinaryStreamWriter, BinaryStreamWriter > split(uint64_t Off) const
Splits the Writer into two Writers at a given offset.
Definition: BinaryStreamWriter.cpp:83
llvm::BinaryStreamWriter::getLength
uint64_t getLength() const
Definition: BinaryStreamWriter.h:184
llvm::support::endianness
endianness
Definition: Endian.h:27
llvm::BinaryStreamWriter::BinaryStreamWriter
BinaryStreamWriter(const BinaryStreamWriter &Other)
Definition: BinaryStreamWriter.h:38
llvm::stream_error_code::invalid_array_size
@ invalid_array_size
Endian.h
llvm::BinaryStreamWriter::BinaryStreamWriter
BinaryStreamWriter()=default
llvm::WritableBinaryStream
A BinaryStream which can be read from as well as written to.
Definition: BinaryStream.h:73
llvm::Value
LLVM Value Representation.
Definition: Value.h:74
llvm::BinaryStreamWriter::operator=
BinaryStreamWriter & operator=(const BinaryStreamWriter &Other)
Definition: BinaryStreamWriter.h:41
llvm::WritableBinaryStreamRef
Definition: BinaryStreamRef.h:220
llvm::BinaryStreamRef
BinaryStreamRef is to BinaryStream what ArrayRef is to an Array.
Definition: BinaryStreamRef.h:155
Other
Optional< std::vector< StOtherPiece > > Other
Definition: ELFYAML.cpp:1198