Subversion Repositories QNX 8.QNX8 LLVM/Clang compiler suite

//===-- DataExtractor.h -----------------------------------------*- C++ -*-===//

//

// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.

// See https://llvm.org/LICENSE.txt for license information.

// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

//

//===----------------------------------------------------------------------===//

#ifndef LLVM_SUPPORT_DATAEXTRACTOR_H

#define LLVM_SUPPORT_DATAEXTRACTOR_H

#include "llvm/ADT/StringRef.h"

#include "llvm/Support/DataTypes.h"

#include "llvm/Support/Error.h"

namespace llvm {

/// An auxiliary type to facilitate extraction of 3-byte entities.

struct Uint24 {

  uint8_t Bytes[3];

  Uint24(uint8_t U) {

    Bytes[0] = Bytes[1] = Bytes[2] = U;

  }

  Uint24(uint8_t U0, uint8_t U1, uint8_t U2) {

    Bytes[0] = U0; Bytes[1] = U1; Bytes[2] = U2;

  }

  uint32_t getAsUint32(bool IsLittleEndian) const {

    int LoIx = IsLittleEndian ? 0 : 2;

    return Bytes[LoIx] + (Bytes[1] << 8) + (Bytes[2-LoIx] << 16);

  }

};

using uint24_t = Uint24;

static_assert(sizeof(uint24_t) == 3, "sizeof(uint24_t) != 3");

/// Needed by swapByteOrder().

inline uint24_t getSwappedBytes(uint24_t C) {

  return uint24_t(C.Bytes[2], C.Bytes[1], C.Bytes[0]);

}

class DataExtractor {

  StringRef Data;

  uint8_t IsLittleEndian;

  uint8_t AddressSize;

public:

  /// A class representing a position in a DataExtractor, as well as any error

  /// encountered during extraction. It enables one to extract a sequence of

  /// values without error-checking and then checking for errors in bulk at the

  /// end. The class holds an Error object, so failing to check the result of

  /// the parse will result in a runtime error. The error flag is sticky and

  /// will cause all subsequent extraction functions to fail without even

  /// attempting to parse and without updating the Cursor offset. After clearing

  /// the error flag, one can again use the Cursor object for parsing.

  class Cursor {

    uint64_t Offset;

    Error Err;

    friend class DataExtractor;

  public:

    /// Construct a cursor for extraction from the given offset.

    explicit Cursor(uint64_t Offset) : Offset(Offset), Err(Error::success()) {}

    /// Checks whether the cursor is valid (i.e. no errors were encountered). In

    /// case of errors, this does not clear the error flag -- one must call

    /// takeError() instead.

    explicit operator bool() { return !Err; }

    /// Return the current position of this Cursor. In the error state this is

    /// the position of the Cursor before the first error was encountered.

    uint64_t tell() const { return Offset; }

    /// Set the cursor to the new offset. This does not impact the error state.

    void seek(uint64_t NewOffSet) { Offset = NewOffSet; }

    /// Return error contained inside this Cursor, if any. Clears the internal

    /// Cursor state.

    Error takeError() { return std::move(Err); }

  };

  /// Construct with a buffer that is owned by the caller.

  ///

  /// This constructor allows us to use data that is owned by the

  /// caller. The data must stay around as long as this object is

  /// valid.

  DataExtractor(StringRef Data, bool IsLittleEndian, uint8_t AddressSize)

    : Data(Data), IsLittleEndian(IsLittleEndian), AddressSize(AddressSize) {}

  DataExtractor(ArrayRef<uint8_t> Data, bool IsLittleEndian,

                uint8_t AddressSize)

      : Data(StringRef(reinterpret_cast<const char *>(Data.data()),

                       Data.size())),

        IsLittleEndian(IsLittleEndian), AddressSize(AddressSize) {}

  /// Get the data pointed to by this extractor.

  StringRef getData() const { return Data; }

  /// Get the endianness for this extractor.

  bool isLittleEndian() const { return IsLittleEndian; }

  /// Get the address size for this extractor.

  uint8_t getAddressSize() const { return AddressSize; }

  /// Set the address size for this extractor.

  void setAddressSize(uint8_t Size) { AddressSize = Size; }

  /// Extract a C string from \a *offset_ptr.

  ///

  /// Returns a pointer to a C String from the data at the offset

  /// pointed to by \a offset_ptr. A variable length NULL terminated C

  /// string will be extracted and the \a offset_ptr will be

  /// updated with the offset of the byte that follows the NULL

  /// terminator byte.

  ///

  /// @param[in,out] OffsetPtr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// @param[in,out] Err

  ///     A pointer to an Error object. Upon return the Error object is set to

  ///     indicate the result (success/failure) of the function. If the Error

  ///     object is already set when calling this function, no extraction is

  ///     performed.

  ///

  /// @return

  ///     A pointer to the C string value in the data. If the offset

  ///     pointed to by \a offset_ptr is out of bounds, or if the

  ///     offset plus the length of the C string is out of bounds,

  ///     NULL will be returned.

  const char *getCStr(uint64_t *OffsetPtr, Error *Err = nullptr) const {

    return getCStrRef(OffsetPtr, Err).data();

  }

  /// Extract a C string from the location given by the cursor. In case of an

  /// extraction error, or if the cursor is already in an error state, a

  /// nullptr is returned.

  const char *getCStr(Cursor &C) const { return getCStrRef(C).data(); }

  /// Extract a C string from \a *offset_ptr.

  ///

  /// Returns a StringRef for the C String from the data at the offset

  /// pointed to by \a offset_ptr. A variable length NULL terminated C

  /// string will be extracted and the \a offset_ptr will be

  /// updated with the offset of the byte that follows the NULL

  /// terminator byte.

  ///

  /// \param[in,out] OffsetPtr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// @param[in,out] Err

  ///     A pointer to an Error object. Upon return the Error object is set to

  ///     indicate the result (success/failure) of the function. If the Error

  ///     object is already set when calling this function, no extraction is

  ///     performed.

  ///

  /// \return

  ///     A StringRef for the C string value in the data. If the offset

  ///     pointed to by \a offset_ptr is out of bounds, or if the

  ///     offset plus the length of the C string is out of bounds,

  ///     a default-initialized StringRef will be returned.

  StringRef getCStrRef(uint64_t *OffsetPtr, Error *Err = nullptr) const;

  /// Extract a C string (as a StringRef) from the location given by the cursor.

  /// In case of an extraction error, or if the cursor is already in an error

  /// state, a default-initialized StringRef is returned.

  StringRef getCStrRef(Cursor &C) const {

    return getCStrRef(&C.Offset, &C.Err);

  }

  /// Extract a fixed length string from \a *OffsetPtr and consume \a Length

  /// bytes.

  ///

  /// Returns a StringRef for the string from the data at the offset

  /// pointed to by \a OffsetPtr. A fixed length C string will be extracted

  /// and the \a OffsetPtr will be advanced by \a Length bytes.

  ///

  /// \param[in,out] OffsetPtr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// \param[in] Length

  ///     The length of the fixed length string to extract. If there are not

  ///     enough bytes in the data to extract the full string, the offset will

  ///     be left unmodified.

  ///

  /// \param[in] TrimChars

  ///     A set of characters to trim from the end of the string. Fixed length

  ///     strings are commonly either NULL terminated by one or more zero

  ///     bytes. Some clients have one or more spaces at the end of the string,

  ///     but a good default is to trim the NULL characters.

  ///

  /// \return

  ///     A StringRef for the C string value in the data. If the offset

  ///     pointed to by \a OffsetPtr is out of bounds, or if the

  ///     offset plus the length of the C string is out of bounds,

  ///     a default-initialized StringRef will be returned.

  StringRef getFixedLengthString(uint64_t *OffsetPtr,

      uint64_t Length, StringRef TrimChars = {"\0", 1}) const;

  /// Extract a fixed number of bytes from the specified offset.

  ///

  /// Returns a StringRef for the bytes from the data at the offset

  /// pointed to by \a OffsetPtr. A fixed length C string will be extracted

  /// and the \a OffsetPtr will be advanced by \a Length bytes.

  ///

  /// \param[in,out] OffsetPtr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// \param[in] Length

  ///     The number of bytes to extract. If there are not enough bytes in the

  ///     data to extract all of the bytes, the offset will be left unmodified.

  ///

  /// @param[in,out] Err

  ///     A pointer to an Error object. Upon return the Error object is set to

  ///     indicate the result (success/failure) of the function. If the Error

  ///     object is already set when calling this function, no extraction is

  ///     performed.

  ///

  /// \return

  ///     A StringRef for the extracted bytes. If the offset pointed to by

  ///     \a OffsetPtr is out of bounds, or if the offset plus the length

  ///     is out of bounds, a default-initialized StringRef will be returned.

  StringRef getBytes(uint64_t *OffsetPtr, uint64_t Length,

                     Error *Err = nullptr) const;

  /// Extract a fixed number of bytes from the location given by the cursor. In

  /// case of an extraction error, or if the cursor is already in an error

  /// state, a default-initialized StringRef is returned.

  StringRef getBytes(Cursor &C, uint64_t Length) {

    return getBytes(&C.Offset, Length, &C.Err);

  }

  /// Extract an unsigned integer of size \a byte_size from \a

  /// *offset_ptr.

  ///

  /// Extract a single unsigned integer value and update the offset

  /// pointed to by \a offset_ptr. The size of the extracted integer

  /// is specified by the \a byte_size argument. \a byte_size should

  /// have a value greater than or equal to one and less than or equal

  /// to eight since the return value is 64 bits wide. Any

  /// \a byte_size values less than 1 or greater than 8 will result in

  /// nothing being extracted, and zero being returned.

  ///

  /// @param[in,out] offset_ptr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// @param[in] byte_size

  ///     The size in byte of the integer to extract.

  ///

  /// @param[in,out] Err

  ///     A pointer to an Error object. Upon return the Error object is set to

  ///     indicate the result (success/failure) of the function. If the Error

  ///     object is already set when calling this function, no extraction is

  ///     performed.

  ///

  /// @return

  ///     The unsigned integer value that was extracted, or zero on

  ///     failure.

  uint64_t getUnsigned(uint64_t *offset_ptr, uint32_t byte_size,

                       Error *Err = nullptr) const;

  /// Extract an unsigned integer of the given size from the location given by

  /// the cursor. In case of an extraction error, or if the cursor is already in

  /// an error state, zero is returned.

  uint64_t getUnsigned(Cursor &C, uint32_t Size) const {

    return getUnsigned(&C.Offset, Size, &C.Err);

  }

  /// Extract an signed integer of size \a byte_size from \a *offset_ptr.

  ///

  /// Extract a single signed integer value (sign extending if required)

  /// and update the offset pointed to by \a offset_ptr. The size of

  /// the extracted integer is specified by the \a byte_size argument.

  /// \a byte_size should have a value greater than or equal to one

  /// and less than or equal to eight since the return value is 64

  /// bits wide. Any \a byte_size values less than 1 or greater than

  /// 8 will result in nothing being extracted, and zero being returned.

  ///

  /// @param[in,out] offset_ptr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// @param[in] size

  ///     The size in bytes of the integer to extract.

  ///

  /// @return

  ///     The sign extended signed integer value that was extracted,

  ///     or zero on failure.

  int64_t getSigned(uint64_t *offset_ptr, uint32_t size) const;

  //------------------------------------------------------------------

  /// Extract an pointer from \a *offset_ptr.

  ///

  /// Extract a single pointer from the data and update the offset

  /// pointed to by \a offset_ptr. The size of the extracted pointer

  /// is \a getAddressSize(), so the address size has to be

  /// set correctly prior to extracting any pointer values.

  ///

  /// @param[in,out] offset_ptr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// @return

  ///     The extracted pointer value as a 64 integer.

  uint64_t getAddress(uint64_t *offset_ptr) const {

    return getUnsigned(offset_ptr, AddressSize);

  }

  /// Extract a pointer-sized unsigned integer from the location given by the

  /// cursor. In case of an extraction error, or if the cursor is already in

  /// an error state, zero is returned.

  uint64_t getAddress(Cursor &C) const { return getUnsigned(C, AddressSize); }

  /// Extract a uint8_t value from \a *offset_ptr.

  ///

  /// Extract a single uint8_t from the binary data at the offset

  /// pointed to by \a offset_ptr, and advance the offset on success.

  ///

  /// @param[in,out] offset_ptr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// @param[in,out] Err

  ///     A pointer to an Error object. Upon return the Error object is set to

  ///     indicate the result (success/failure) of the function. If the Error

  ///     object is already set when calling this function, no extraction is

  ///     performed.

  ///

  /// @return

  ///     The extracted uint8_t value.

  uint8_t getU8(uint64_t *offset_ptr, Error *Err = nullptr) const;

  /// Extract a single uint8_t value from the location given by the cursor. In

  /// case of an extraction error, or if the cursor is already in an error

  /// state, zero is returned.

  uint8_t getU8(Cursor &C) const { return getU8(&C.Offset, &C.Err); }

  /// Extract \a count uint8_t values from \a *offset_ptr.

  ///

  /// Extract \a count uint8_t values from the binary data at the

  /// offset pointed to by \a offset_ptr, and advance the offset on

  /// success. The extracted values are copied into \a dst.

  ///

  /// @param[in,out] offset_ptr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// @param[out] dst

  ///     A buffer to copy \a count uint8_t values into. \a dst must

  ///     be large enough to hold all requested data.

  ///

  /// @param[in] count

  ///     The number of uint8_t values to extract.

  ///

  /// @return

  ///     \a dst if all values were properly extracted and copied,

  ///     NULL otherise.

  uint8_t *getU8(uint64_t *offset_ptr, uint8_t *dst, uint32_t count) const;

  /// Extract \a Count uint8_t values from the location given by the cursor and

  /// store them into the destination buffer. In case of an extraction error, or

  /// if the cursor is already in an error state, a nullptr is returned and the

  /// destination buffer is left unchanged.

  uint8_t *getU8(Cursor &C, uint8_t *Dst, uint32_t Count) const;

  /// Extract \a Count uint8_t values from the location given by the cursor and

  /// store them into the destination vector. The vector is resized to fit the

  /// extracted data. In case of an extraction error, or if the cursor is

  /// already in an error state, the destination vector is left unchanged and

  /// cursor is placed into an error state.

  void getU8(Cursor &C, SmallVectorImpl<uint8_t> &Dst, uint32_t Count) const {

    if (isValidOffsetForDataOfSize(C.Offset, Count))

      Dst.resize(Count);

    // This relies on the fact that getU8 will not attempt to write to the

    // buffer if isValidOffsetForDataOfSize(C.Offset, Count) is false.

    getU8(C, Dst.data(), Count);

  }

  //------------------------------------------------------------------

  /// Extract a uint16_t value from \a *offset_ptr.

  ///

  /// Extract a single uint16_t from the binary data at the offset

  /// pointed to by \a offset_ptr, and update the offset on success.

  ///

  /// @param[in,out] offset_ptr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// @param[in,out] Err

  ///     A pointer to an Error object. Upon return the Error object is set to

  ///     indicate the result (success/failure) of the function. If the Error

  ///     object is already set when calling this function, no extraction is

  ///     performed.

  ///

  /// @return

  ///     The extracted uint16_t value.

  //------------------------------------------------------------------

  uint16_t getU16(uint64_t *offset_ptr, Error *Err = nullptr) const;

  /// Extract a single uint16_t value from the location given by the cursor. In

  /// case of an extraction error, or if the cursor is already in an error

  /// state, zero is returned.

  uint16_t getU16(Cursor &C) const { return getU16(&C.Offset, &C.Err); }

  /// Extract \a count uint16_t values from \a *offset_ptr.

  ///

  /// Extract \a count uint16_t values from the binary data at the

  /// offset pointed to by \a offset_ptr, and advance the offset on

  /// success. The extracted values are copied into \a dst.

  ///

  /// @param[in,out] offset_ptr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// @param[out] dst

  ///     A buffer to copy \a count uint16_t values into. \a dst must

  ///     be large enough to hold all requested data.

  ///

  /// @param[in] count

  ///     The number of uint16_t values to extract.

  ///

  /// @return

  ///     \a dst if all values were properly extracted and copied,

  ///     NULL otherise.

  uint16_t *getU16(uint64_t *offset_ptr, uint16_t *dst, uint32_t count) const;

  /// Extract a 24-bit unsigned value from \a *offset_ptr and return it

  /// in a uint32_t.

  ///

  /// Extract 3 bytes from the binary data at the offset pointed to by

  /// \a offset_ptr, construct a uint32_t from them and update the offset

  /// on success.

  ///

  /// @param[in,out] OffsetPtr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the 3 bytes if the value is extracted correctly. If the offset

  ///     is out of bounds or there are not enough bytes to extract this value,

  ///     the offset will be left unmodified.

  ///

  /// @param[in,out] Err

  ///     A pointer to an Error object. Upon return the Error object is set to

  ///     indicate the result (success/failure) of the function. If the Error

  ///     object is already set when calling this function, no extraction is

  ///     performed.

  ///

  /// @return

  ///     The extracted 24-bit value represented in a uint32_t.

  uint32_t getU24(uint64_t *OffsetPtr, Error *Err = nullptr) const;

  /// Extract a single 24-bit unsigned value from the location given by the

  /// cursor. In case of an extraction error, or if the cursor is already in an

  /// error state, zero is returned.

  uint32_t getU24(Cursor &C) const { return getU24(&C.Offset, &C.Err); }

  /// Extract a uint32_t value from \a *offset_ptr.

  ///

  /// Extract a single uint32_t from the binary data at the offset

  /// pointed to by \a offset_ptr, and update the offset on success.

  ///

  /// @param[in,out] offset_ptr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// @param[in,out] Err

  ///     A pointer to an Error object. Upon return the Error object is set to

  ///     indicate the result (success/failure) of the function. If the Error

  ///     object is already set when calling this function, no extraction is

  ///     performed.

  ///

  /// @return

  ///     The extracted uint32_t value.

  uint32_t getU32(uint64_t *offset_ptr, Error *Err = nullptr) const;

  /// Extract a single uint32_t value from the location given by the cursor. In

  /// case of an extraction error, or if the cursor is already in an error

  /// state, zero is returned.

  uint32_t getU32(Cursor &C) const { return getU32(&C.Offset, &C.Err); }

  /// Extract \a count uint32_t values from \a *offset_ptr.

  ///

  /// Extract \a count uint32_t values from the binary data at the

  /// offset pointed to by \a offset_ptr, and advance the offset on

  /// success. The extracted values are copied into \a dst.

  ///

  /// @param[in,out] offset_ptr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// @param[out] dst

  ///     A buffer to copy \a count uint32_t values into. \a dst must

  ///     be large enough to hold all requested data.

  ///

  /// @param[in] count

  ///     The number of uint32_t values to extract.

  ///

  /// @return

  ///     \a dst if all values were properly extracted and copied,

  ///     NULL otherise.

  uint32_t *getU32(uint64_t *offset_ptr, uint32_t *dst, uint32_t count) const;

  /// Extract a uint64_t value from \a *offset_ptr.

  ///

  /// Extract a single uint64_t from the binary data at the offset

  /// pointed to by \a offset_ptr, and update the offset on success.

  ///

  /// @param[in,out] offset_ptr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// @param[in,out] Err

  ///     A pointer to an Error object. Upon return the Error object is set to

  ///     indicate the result (success/failure) of the function. If the Error

  ///     object is already set when calling this function, no extraction is

  ///     performed.

  ///

  /// @return

  ///     The extracted uint64_t value.

  uint64_t getU64(uint64_t *offset_ptr, Error *Err = nullptr) const;

  /// Extract a single uint64_t value from the location given by the cursor. In

  /// case of an extraction error, or if the cursor is already in an error

  /// state, zero is returned.

  uint64_t getU64(Cursor &C) const { return getU64(&C.Offset, &C.Err); }

  /// Extract \a count uint64_t values from \a *offset_ptr.

  ///

  /// Extract \a count uint64_t values from the binary data at the

  /// offset pointed to by \a offset_ptr, and advance the offset on

  /// success. The extracted values are copied into \a dst.

  ///

  /// @param[in,out] offset_ptr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// @param[out] dst

  ///     A buffer to copy \a count uint64_t values into. \a dst must

  ///     be large enough to hold all requested data.

  ///

  /// @param[in] count

  ///     The number of uint64_t values to extract.

  ///

  /// @return

  ///     \a dst if all values were properly extracted and copied,

  ///     NULL otherise.

  uint64_t *getU64(uint64_t *offset_ptr, uint64_t *dst, uint32_t count) const;

  /// Extract a signed LEB128 value from \a *offset_ptr.

  ///

  /// Extracts an signed LEB128 number from this object's data

  /// starting at the offset pointed to by \a offset_ptr. The offset

  /// pointed to by \a offset_ptr will be updated with the offset of

  /// the byte following the last extracted byte.

  ///

  /// @param[in,out] OffsetPtr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// @param[in,out] Err

  ///     A pointer to an Error object. Upon return the Error object is set to

  ///     indicate the result (success/failure) of the function. If the Error

  ///     object is already set when calling this function, no extraction is

  ///     performed.

  ///

  /// @return

  ///     The extracted signed integer value.

  int64_t getSLEB128(uint64_t *OffsetPtr, Error *Err = nullptr) const;

  /// Extract an signed LEB128 value from the location given by the cursor.

  /// In case of an extraction error, or if the cursor is already in an error

  /// state, zero is returned.

  int64_t getSLEB128(Cursor &C) const { return getSLEB128(&C.Offset, &C.Err); }

  /// Extract a unsigned LEB128 value from \a *offset_ptr.

  ///

  /// Extracts an unsigned LEB128 number from this object's data

  /// starting at the offset pointed to by \a offset_ptr. The offset

  /// pointed to by \a offset_ptr will be updated with the offset of

  /// the byte following the last extracted byte.

  ///

  /// @param[in,out] offset_ptr

  ///     A pointer to an offset within the data that will be advanced

  ///     by the appropriate number of bytes if the value is extracted

  ///     correctly. If the offset is out of bounds or there are not

  ///     enough bytes to extract this value, the offset will be left

  ///     unmodified.

  ///

  /// @param[in,out] Err

  ///     A pointer to an Error object. Upon return the Error object is set to

  ///     indicate the result (success/failure) of the function. If the Error

  ///     object is already set when calling this function, no extraction is

  ///     performed.

  ///

  /// @return

  ///     The extracted unsigned integer value.

  uint64_t getULEB128(uint64_t *offset_ptr, llvm::Error *Err = nullptr) const;

  /// Extract an unsigned LEB128 value from the location given by the cursor.

  /// In case of an extraction error, or if the cursor is already in an error

  /// state, zero is returned.

  uint64_t getULEB128(Cursor &C) const { return getULEB128(&C.Offset, &C.Err); }

  /// Advance the Cursor position by the given number of bytes. No-op if the

  /// cursor is in an error state.

  void skip(Cursor &C, uint64_t Length) const;

  /// Return true iff the cursor is at the end of the buffer, regardless of the

  /// error state of the cursor. The only way both eof and error states can be

  /// true is if one attempts a read while the cursor is at the very end of the

  /// data buffer.

  bool eof(const Cursor &C) const { return size() == C.Offset; }

  /// Test the validity of \a offset.

  ///

  /// @return

  ///     \b true if \a offset is a valid offset into the data in this

  ///     object, \b false otherwise.

  bool isValidOffset(uint64_t offset) const { return size() > offset; }

  /// Test the availability of \a length bytes of data from \a offset.

  ///

  /// @return

  ///     \b true if \a offset is a valid offset and there are \a

  ///     length bytes available at that offset, \b false otherwise.

  bool isValidOffsetForDataOfSize(uint64_t offset, uint64_t length) const {

    return offset + length >= offset && isValidOffset(offset + length - 1);

  }

  /// Test the availability of enough bytes of data for a pointer from

  /// \a offset. The size of a pointer is \a getAddressSize().

  ///

  /// @return

  ///     \b true if \a offset is a valid offset and there are enough

  ///     bytes for a pointer available at that offset, \b false

  ///     otherwise.

  bool isValidOffsetForAddress(uint64_t offset) const {

    return isValidOffsetForDataOfSize(offset, AddressSize);

  }

  /// Return the number of bytes in the underlying buffer.

  size_t size() const { return Data.size(); }

protected:

  // Make it possible for subclasses to access these fields without making them

  // public.

  static uint64_t &getOffset(Cursor &C) { return C.Offset; }

  static Error &getError(Cursor &C) { return C.Err; }

private:

  /// If it is possible to read \a Size bytes at offset \a Offset, returns \b

  /// true. Otherwise, returns \b false. If \a E is not nullptr, also sets the

  /// error object to indicate an error.

  bool prepareRead(uint64_t Offset, uint64_t Size, Error *E) const;

  template <typename T> T getU(uint64_t *OffsetPtr, Error *Err) const;

  template <typename T>

  T *getUs(uint64_t *OffsetPtr, T *Dst, uint32_t Count, Error *Err) const;

};

} // namespace llvm

#endif