include/llvm/Support/BinaryStreamWriter.h

   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/STLExtras.h"
  14 #include "llvm/ADT/StringRef.h"
  15 #include "llvm/Support/BinaryStreamArray.h"
  16 #include "llvm/Support/BinaryStreamError.h"
  17 #include "llvm/Support/BinaryStreamRef.h"
  18 #include "llvm/Support/Endian.h"
  19 #include "llvm/Support/Error.h"
  20 #include <cstdint>
  21 #include <type_traits>
  22 #include <utility>
  23
  24 namespace llvm {
  25
  26 /// Provides write only access to a subclass of `WritableBinaryStream`.
  27 /// Provides bounds checking and helpers for writing certain common data types
  28 /// such as null-terminated strings, integers in various flavors of endianness,
  29 /// etc.  Can be subclassed to provide reading and writing of custom datatypes,
  30 /// although no methods are overridable.
  31 class BinaryStreamWriter {
  32 public:
  33   BinaryStreamWriter() = default;
  34   explicit BinaryStreamWriter(WritableBinaryStreamRef Ref);
  35   explicit BinaryStreamWriter(WritableBinaryStream &Stream);
  36   explicit BinaryStreamWriter(MutableArrayRef<uint8_t> Data,
  37                               llvm::support::endianness Endian);
  38
  39   BinaryStreamWriter(const BinaryStreamWriter &Other)
  40       : Stream(Other.Stream), Offset(Other.Offset) {}
  41
  42   BinaryStreamWriter &operator=(const BinaryStreamWriter &Other) {
  43     Stream = Other.Stream;
  44     Offset = Other.Offset;
  45     return *this;
  46   }
  47
  48   virtual ~BinaryStreamWriter() {}
  49
  50   /// Write the bytes specified in \p Buffer to the underlying stream.
  51   /// On success, updates the offset so that subsequent writes will occur
  52   /// at the next unwritten position.
  53   ///
  54   /// \returns a success error code if the data was successfully written,
  55   /// otherwise returns an appropriate error code.
  56   Error writeBytes(ArrayRef<uint8_t> Buffer);
  57
  58   /// Write the integer \p Value to the underlying stream in the
  59   /// specified endianness.  On success, updates the offset so that
  60   /// subsequent writes occur at the next unwritten position.
  61   ///
  62   /// \returns a success error code if the data was successfully written,
  63   /// otherwise returns an appropriate error code.
  64   template <typename T> Error writeInteger(T Value) {
  65     static_assert(std::is_integral<T>::value,
  66                   "Cannot call writeInteger with non-integral value!");
  67     uint8_t Buffer[sizeof(T)];
  68     llvm::support::endian::write<T, llvm::support::unaligned>(
  69         Buffer, Value, Stream.getEndian());
  70     return writeBytes(Buffer);
  71   }
  72
  73   /// Similar to writeInteger
  74   template <typename T> Error writeEnum(T Num) {
  75     static_assert(std::is_enum<T>::value,
  76                   "Cannot call writeEnum with non-Enum type");
  77
  78     using U = typename std::underlying_type<T>::type;
  79     return writeInteger<U>(static_cast<U>(Num));
  80   }
  81
  82   /// Write the string \p Str to the underlying stream followed by a null
  83   /// terminator.  On success, updates the offset so that subsequent writes
  84   /// occur at the next unwritten position.  \p Str need not be null terminated
  85   /// on input.
  86   ///
  87   /// \returns a success error code if the data was successfully written,
  88   /// otherwise returns an appropriate error code.
  89   Error writeCString(StringRef Str);
  90
  91   /// Write the string \p Str to the underlying stream without a null
  92   /// terminator.  On success, updates the offset so that subsequent writes
  93   /// occur at the next unwritten position.
  94   ///
  95   /// \returns a success error code if the data was successfully written,
  96   /// otherwise returns an appropriate error code.
  97   Error writeFixedString(StringRef Str);
  98
  99   /// Efficiently reads all data from \p Ref, and writes it to this stream.
 100   /// This operation will not invoke any copies of the source data, regardless
 101   /// of the source stream's implementation.
 102   ///
 103   /// \returns a success error code if the data was successfully written,
 104   /// otherwise returns an appropriate error code.
 105   Error writeStreamRef(BinaryStreamRef Ref);
 106
 107   /// Efficiently reads \p Size bytes from \p Ref, and writes it to this stream.
 108   /// This operation will not invoke any copies of the source data, regardless
 109   /// of the source stream's implementation.
 110   ///
 111   /// \returns a success error code if the data was successfully written,
 112   /// otherwise returns an appropriate error code.
 113   Error writeStreamRef(BinaryStreamRef Ref, uint32_t Size);
 114
 115   /// Writes the object \p Obj to the underlying stream, as if by using memcpy.
 116   /// It is up to the caller to ensure that type of \p Obj can be safely copied
 117   /// in this fashion, as no checks are made to ensure that this is safe.
 118   ///
 119   /// \returns a success error code if the data was successfully written,
 120   /// otherwise returns an appropriate error code.
 121   template <typename T> Error writeObject(const T &Obj) {
 122     static_assert(!std::is_pointer<T>::value,
 123                   "writeObject should not be used with pointers, to write "
 124                   "the pointed-to value dereference the pointer before calling "
 125                   "writeObject");
 126     return writeBytes(
 127         ArrayRef<uint8_t>(reinterpret_cast<const uint8_t *>(&Obj), sizeof(T)));
 128   }
 129
 130   /// Writes an array of objects of type T to the underlying stream, as if by
 131   /// using memcpy.  It is up to the caller to ensure that type of \p Obj can
 132   /// be safely copied in this fashion, as no checks are made to ensure that
 133   /// this is safe.
 134   ///
 135   /// \returns a success error code if the data was successfully written,
 136   /// otherwise returns an appropriate error code.
 137   template <typename T> Error writeArray(ArrayRef<T> Array) {
 138     if (Array.empty())
 139       return Error::success();
 140     if (Array.size() > UINT32_MAX / sizeof(T))
 141       return make_error<BinaryStreamError>(
 142           stream_error_code::invalid_array_size);
 143
 144     return writeBytes(
 145         ArrayRef<uint8_t>(reinterpret_cast<const uint8_t *>(Array.data()),
 146                           Array.size() * sizeof(T)));
 147   }
 148
 149   /// Writes all data from the array \p Array to the underlying stream.
 150   ///
 151   /// \returns a success error code if the data was successfully written,
 152   /// otherwise returns an appropriate error code.
 153   template <typename T, typename U>
 154   Error writeArray(VarStreamArray<T, U> Array) {
 155     return writeStreamRef(Array.getUnderlyingStream());
 156   }
 157
 158   /// Writes all elements from the array \p Array to the underlying stream.
 159   ///
 160   /// \returns a success error code if the data was successfully written,
 161   /// otherwise returns an appropriate error code.
 162   template <typename T> Error writeArray(FixedStreamArray<T> Array) {
 163     return writeStreamRef(Array.getUnderlyingStream());
 164   }
 165
 166   /// Splits the Writer into two Writers at a given offset.
 167   std::pair<BinaryStreamWriter, BinaryStreamWriter> split(uint32_t Off) const;
 168
 169   void setOffset(uint32_t Off) { Offset = Off; }
 170   uint32_t getOffset() const { return Offset; }
 171   uint32_t getLength() const { return Stream.getLength(); }
 172   uint32_t bytesRemaining() const { return getLength() - getOffset(); }
 173   Error padToAlignment(uint32_t Align);
 174
 175 protected:
 176   WritableBinaryStreamRef Stream;
 177   uint32_t Offset = 0;
 178 };
 179
 180 } // end namespace llvm
 181
 182 #endif // LLVM_SUPPORT_BINARYSTREAMWRITER_H