xref: /freebsd-10.0-release/contrib/llvm/tools/lldb/include/lldb/Core/DataExtractor.h

//===-- DataExtractor.h -----------------------------------------*- C++ -*-===//
//
//                     The LLVM Compiler Infrastructure
//
// This file is distributed under the University of Illinois Open Source
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//

#ifndef liblldb_DataExtractor_h_
#define liblldb_DataExtractor_h_
#if defined (__cplusplus)


#include "lldb/lldb-private.h"
#include <limits.h>
#include <stdint.h>
#include <string.h>

namespace lldb_private {

//----------------------------------------------------------------------
/// @class DataExtractor DataExtractor.h "lldb/Core/DataExtractor.h"
/// @brief An data extractor class.
///
/// DataExtractor is a class that can extract data (swapping if needed)
/// from a data buffer. The data buffer can be caller owned, or can be
/// shared data that can be shared between multiple DataExtractor
/// instances. Multiple DataExtractor objects can share the same data,
/// yet extract values in different address sizes and byte order modes.
/// Each object can have a unique position in the shared data and extract
/// data from different offsets.
///
/// @see DataBuffer
//----------------------------------------------------------------------
class DataExtractor
{
public:
    //------------------------------------------------------------------
    /// @typedef DataExtractor::Type
    /// @brief Type enumerations used in the dump routines.
    /// @see DataExtractor::Dump()
    /// @see DataExtractor::DumpRawHexBytes()
    //------------------------------------------------------------------
    typedef enum
    {
        TypeUInt8,      ///< Format output as unsigned 8 bit integers
        TypeChar,       ///< Format output as characters
        TypeUInt16,     ///< Format output as unsigned 16 bit integers
        TypeUInt32,     ///< Format output as unsigned 32 bit integers
        TypeUInt64,     ///< Format output as unsigned 64 bit integers
        TypePointer,    ///< Format output as pointers
        TypeULEB128,    ///< Format output as ULEB128 numbers
        TypeSLEB128     ///< Format output as SLEB128 numbers
    } Type;

    static void
    DumpHexBytes (Stream *s,
                  const void *src,
                  size_t src_len,
                  uint32_t bytes_per_line,
                  lldb::addr_t base_addr); // Pass LLDB_INVALID_ADDRESS to not show address at start of line
    //------------------------------------------------------------------
    /// Default constructor.
    ///
    /// Initialize all members to a default empty state.
    //------------------------------------------------------------------
    DataExtractor ();

    //------------------------------------------------------------------
    /// 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.
    ///
    /// @param[in] data
    ///     A pointer to caller owned data.
    ///
    /// @param[in] data_length
    ///     The length in bytes of \a data.
    ///
    /// @param[in] byte_order
    ///     A byte order of the data that we are extracting from.
    ///
    /// @param[in] addr_size
    ///     A new address byte size value.
    //------------------------------------------------------------------
    DataExtractor (const void* data, lldb::offset_t data_length, lldb::ByteOrder byte_order, uint32_t addr_size);

    //------------------------------------------------------------------
    /// Construct with shared data.
    ///
    /// Copies the data shared pointer which adds a reference to the
    /// contained in \a data_sp. The shared data reference is reference
    /// counted to ensure the data lives as long as anyone still has a
    /// valid shared pointer to the data in \a data_sp.
    ///
    /// @param[in] data_sp
    ///     A shared pointer to data.
    ///
    /// @param[in] byte_order
    ///     A byte order of the data that we are extracting from.
    ///
    /// @param[in] addr_size
    ///     A new address byte size value.
    //------------------------------------------------------------------
    DataExtractor (const lldb::DataBufferSP& data_sp, lldb::ByteOrder byte_order, uint32_t addr_size);

    //------------------------------------------------------------------
    /// Construct with a subset of \a data.
    ///
    /// Initialize this object with a subset of the data bytes in \a
    /// data. If \a data contains shared data, then a reference to the
    /// shared data will be added to ensure the shared data stays around
    /// as long as any objects have references to the shared data. The
    /// byte order value and the address size settings are copied from \a
    /// data. If \a offset is not a valid offset in \a data, then no
    /// reference to the shared data will be added. If there are not
    /// \a length bytes available in \a data starting at \a offset,
    /// the length will be truncated to contain as many bytes as
    /// possible.
    ///
    /// @param[in] data
    ///     Another DataExtractor object that contains data.
    ///
    /// @param[in] offset
    ///     The offset into \a data at which the subset starts.
    ///
    /// @param[in] length
    ///     The length in bytes of the subset of data.
    //------------------------------------------------------------------
    DataExtractor (const DataExtractor& data, lldb::offset_t offset, lldb::offset_t length);

    DataExtractor (const DataExtractor& rhs);
    //------------------------------------------------------------------
    /// Assignment operator.
    ///
    /// Copies all data, byte order and address size settings from \a rhs into
    /// this object. If \a rhs contains shared data, a reference to that
    /// shared data will be added.
    ///
    /// @param[in] rhs
    ///     Another DataExtractor object to copy.
    ///
    /// @return
    ///     A const reference to this object.
    //------------------------------------------------------------------
    const DataExtractor&
    operator= (const DataExtractor& rhs);

    //------------------------------------------------------------------
    /// Destructor
    ///
    /// If this object contains a valid shared data reference, the
    /// reference count on the data will be decremented, and if zero,
    /// the data will be freed.
    //------------------------------------------------------------------
    ~DataExtractor ();

    //------------------------------------------------------------------
    /// Clears the object state.
    ///
    /// Clears the object contents back to a default invalid state, and
    /// release any references to shared data that this object may
    /// contain.
    //------------------------------------------------------------------
    void
    Clear ();

    //------------------------------------------------------------------
    /// Dumps the binary data as \a type objects to stream \a s (or to
    /// Log() if \a s is NULL) starting \a offset bytes into the data
    /// and stopping after dumping \a length bytes. The offset into the
    /// data is displayed at the beginning of each line and can be
    /// offset by base address \a base_addr. \a num_per_line objects
    /// will be displayed on each line.
    ///
    /// @param[in] s
    ///     The stream to dump the output to. If NULL the output will
    ///     be dumped to Log().
    ///
    /// @param[in] offset
    ///     The offset into the data at which to start dumping.
    ///
    /// @param[in] length
    ///     The number of bytes to dump.
    ///
    /// @param[in] base_addr
    ///     The base address that gets added to the offset displayed on
    ///     each line.
    ///
    /// @param[in] num_per_line
    ///     The number of \a type objects to display on each line.
    ///
    /// @param[in] type
    ///     The type of objects to use when dumping data from this
    ///     object. See DataExtractor::Type.
    ///
    /// @param[in] type_format
    ///     The optional format to use for the \a type objects. If this
    ///     is NULL, the default format for the \a type will be used.
    ///
    /// @return
    ///     The offset at which dumping ended.
    //------------------------------------------------------------------
    lldb::offset_t
    PutToLog (Log *log,
              lldb::offset_t offset,
              lldb::offset_t length,
              uint64_t base_addr,
              uint32_t num_per_line,
              Type type,
              const char *type_format = NULL) const;

    //------------------------------------------------------------------
    /// Dumps \a item_count objects into the stream \a s.
    ///
    /// Dumps \a item_count objects using \a item_format, each of which
    /// are \a item_byte_size bytes long starting at offset \a offset
    /// bytes into the contained data, into the stream \a s. \a
    /// num_per_line objects will be dumped on each line before a new
    /// line will be output. If \a base_addr is a valid address, then
    /// each new line of output will be prededed by the address value
    /// plus appropriate offset, and a colon and space. Bitfield values
    /// can be dumped by calling this function multiple times with the
    /// same start offset, format and size, yet differing \a
    /// item_bit_size and \a item_bit_offset values.
    ///
    /// @param[in] s
    ///     The stream to dump the output to. This value can not be NULL.
    ///
    /// @param[in] offset
    ///     The offset into the data at which to start dumping.
    ///
    /// @param[in] item_format
    ///     The format to use when dumping each item.
    ///
    /// @param[in] item_byte_size
    ///     The byte size of each item.
    ///
    /// @param[in] item_count
    ///     The number of items to dump.
    ///
    /// @param[in] num_per_line
    ///     The number of items to display on each line.
    ///
    /// @param[in] base_addr
    ///     The base address that gets added to the offset displayed on
    ///     each line if the value is valid. Is \a base_addr is
    ///     LLDB_INVALID_ADDRESS then no address values will be prepended
    ///     to any lines.
    ///
    /// @param[in] item_bit_size
    ///     If the value to display is a bitfield, this value should
    ///     be the number of bits that the bitfield item has within the
    ///     item's byte size value. This function will need to be called
    ///     multiple times with identical \a offset and \a item_byte_size
    ///     values in order to display multiple bitfield values that
    ///     exist within the same integer value. If the items being
    ///     displayed are not bitfields, this value should be zero.
    ///
    /// @param[in] item_bit_offset
    ///     If the value to display is a bitfield, this value should
    ///     be the offset in bits, or shift right amount, that the
    ///     bitfield item occupies within the item's byte size value.
    ///     This function will need to be called multiple times with
    ///     identical \a offset and \a item_byte_size values in order
    ///     to display multiple bitfield values that exist within the
    ///     same integer value. If the items being displayed are not
    ///     bitfields, this value should be zero.
    ///
    /// @return
    ///     The offset at which dumping ended.
    //------------------------------------------------------------------
    lldb::offset_t
    Dump (Stream *s,
          lldb::offset_t offset,
          lldb::Format item_format,
          size_t item_byte_size,
          size_t item_count,
          size_t num_per_line,
          uint64_t base_addr,
          uint32_t item_bit_size,
          uint32_t item_bit_offset,
          ExecutionContextScope *exe_scope = NULL) const;

    //------------------------------------------------------------------
    /// Dump a UUID value at \a offset.
    ///
    /// Dump a UUID starting at \a offset bytes into this object's data.
    /// If the stream \a s is NULL, the output will be sent to Log().
    ///
    /// @param[in] s
    ///     The stream to dump the output to. If NULL the output will
    ///     be dumped to Log().
    ///
    /// @param[in] offset
    ///     The offset into the data at which to extract and dump a
    ///     UUID value.
    //------------------------------------------------------------------
    void
    DumpUUID (Stream *s, lldb::offset_t offset) const;

    //------------------------------------------------------------------
    /// Extract an arbitrary number of bytes in the specified byte
    /// order.
    ///
    /// Attemps to extract \a length bytes starting at \a offset bytes
    /// into this data in the requested byte order (\a dst_byte_order)
    /// and place the results in \a dst. \a dst must be at least \a
    /// length bytes long.
    ///
    /// @param[in] offset
    ///     The offset in bytes into the contained data at which to
    ///     start extracting.
    ///
    /// @param[in] length
    ///     The number of bytes to extract.
    ///
    /// @param[in] dst_byte_order
    ///     A byte order of the data that we want when the value in
    ///     copied to \a dst.
    ///
    /// @param[out] dst
    ///     The buffer that will receive the extracted value if there
    ///     are enough bytes available in the current data.
    ///
    /// @return
    ///     The number of bytes that were extracted which will be \a
    ///     length when the value is successfully extracted, or zero
    ///     if there aren't enough bytes at the specified offset.
    //------------------------------------------------------------------
    size_t
    ExtractBytes (lldb::offset_t offset, lldb::offset_t length, lldb::ByteOrder dst_byte_order, void *dst) const;

    //------------------------------------------------------------------
    /// Extract an address from \a *offset_ptr.
    ///
    /// Extract a single address from the data and update the offset
    /// pointed to by \a offset_ptr. The size of the extracted address
    /// comes from the \a m_addr_size member variable and should be
    /// set correctly prior to extracting any address 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 address value.
    //------------------------------------------------------------------
    uint64_t
    GetAddress (lldb::offset_t *offset_ptr) const;

    uint64_t
    GetAddress_unchecked (lldb::offset_t *offset_ptr) const;

    //------------------------------------------------------------------
    /// Get the current address size.
    ///
    /// Return the size in bytes of any address values this object will
    /// extract.
    ///
    /// @return
    ///     The size in bytes of address values that will be extracted.
    //------------------------------------------------------------------
    uint32_t
    GetAddressByteSize () const
    {
        return m_addr_size;
    }

    //------------------------------------------------------------------
    /// Get the number of bytes contained in this object.
    ///
    /// @return
    ///     The total number of bytes of data this object refers to.
    //------------------------------------------------------------------
    uint64_t
    GetByteSize () const
    {
        return m_end - m_start;
    }

    //------------------------------------------------------------------
    /// 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] 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
    ///     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 (lldb::offset_t *offset_ptr) const;

    //------------------------------------------------------------------
    /// Extract a C string from \a *offset_ptr with field size \a len.
    ///
    /// Returns a pointer to a C String from the data at the offset
    /// pointed to by \a offset_ptr, with a field length of \a len.
    /// A NULL terminated C string will be extracted and the \a offset_ptr
    /// will be updated with the offset of the byte that follows the fixed
    /// length field.
    ///
    /// @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
    ///     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 field is out of bounds, or if
    ///     the field does not contain a NULL terminator byte, NULL will
    ///     be returned.
    const char *
    GetCStr (lldb::offset_t *offset_ptr, lldb::offset_t len) const;

    //------------------------------------------------------------------
    /// Extract \a length bytes from \a *offset_ptr.
    ///
    /// Returns a pointer to a bytes in this object's data at the offset
    /// pointed to by \a offset_ptr. If \a length is zero or too large,
    /// then the offset pointed to by \a offset_ptr will not be updated
    /// and NULL will be 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] length
    ///     The optional length of a string to extract. If the value is
    ///     zero, a NULL terminated C string will be extracted.
    ///
    /// @return
    ///     A pointer to the bytes in this object's data if the offset
    ///     and length are valid, or NULL otherwise.
    //------------------------------------------------------------------
    const void*
    GetData (lldb::offset_t *offset_ptr, lldb::offset_t length) const
    {
        const uint8_t *ptr = PeekData (*offset_ptr, length);
        if (ptr)
            *offset_ptr += length;
        return ptr;
    }

    //------------------------------------------------------------------
    /// Copy \a dst_len bytes from \a *offset_ptr and ensure the copied
    /// data is treated as a value that can be swapped to match the
    /// specified byte order.
    ///
    /// For values that are larger than the supported integer sizes,
    /// this function can be used to extract data in a specified byte
    /// order. It can also be used to copy a smaller integer value from
    /// to a larger value. The extra bytes left over will be padded
    /// correctly according to the byte order of this object and the
    /// \a dst_byte_order. This can be very handy when say copying a
    /// partial data value into a register.
    ///
    /// @param[in] src_offset
    ///     The offset into this data from which to start copying an
    ///     endian entity
    ///
    /// @param[in] src_len
    ///     The length of the endian data to copy from this object
    ///     into the \a dst object
    ///
    /// @param[out] dst
    ///     The buffer where to place the endian data. The data might
    ///     need to be byte swapped (and appropriately padded with
    ///     zeroes if \a src_len != \a dst_len) if \a dst_byte_order
    ///     does not match the byte order in this object.
    ///
    /// @param[in] dst_len
    ///     The length number of bytes that the endian value will
    ///     occupy is \a dst.
    ///
    /// @param[in] byte_order
    ///     The byte order that the endian value should be in the \a dst
    ///     buffer.
    ///
    /// @return
    ///     Returns the number of bytes that were copied, or zero if
    ///     anything goes wrong.
    //------------------------------------------------------------------
    lldb::offset_t
    CopyByteOrderedData (lldb::offset_t src_offset,
                         lldb::offset_t src_len,
                         void *dst,
                         lldb::offset_t dst_len,
                         lldb::ByteOrder dst_byte_order) const;

    //------------------------------------------------------------------
    /// Get the data end pointer.
    ///
    /// @return
    ///     Returns a pointer to the next byte contained in this
    ///     object's data, or NULL of there is no data in this object.
    //------------------------------------------------------------------
    const uint8_t *
    GetDataEnd () const
    {
        return m_end;
    }

    //------------------------------------------------------------------
    /// Get the shared data offset.
    ///
    /// Get the offset of the first byte of data in the shared data (if
    /// any).
    ///
    /// @return
    ///     If this object contains shared data, this function returns
    ///     the offset in bytes into that shared data, zero otherwise.
    //------------------------------------------------------------------
    size_t
    GetSharedDataOffset () const;

    //------------------------------------------------------------------
    /// Get a the data start pointer.
    ///
    /// @return
    ///     Returns a pointer to the first byte contained in this
    ///     object's data, or NULL of there is no data in this object.
    //------------------------------------------------------------------
    const uint8_t *
    GetDataStart () const
    {
        return m_start;
    }


    //------------------------------------------------------------------
    /// Extract a float from \a *offset_ptr.
    ///
    /// Extract a single float value.
    ///
    /// @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 floating value that was extracted, or zero on failure.
    //------------------------------------------------------------------
    float
    GetFloat (lldb::offset_t *offset_ptr) const;

    double
    GetDouble (lldb::offset_t *offset_ptr) const;

    long double
    GetLongDouble (lldb::offset_t *offset_ptr) const;

    //------------------------------------------------------------------
    /// Extract a GNU encoded pointer value from \a *offset_ptr.
    ///
    /// @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] eh_ptr_enc
    ///     The GNU pointer encoding type.
    ///
    /// @param[in] pc_rel_addr
    ///     The PC relative address to use when the encoding is
    ///     \c DW_GNU_EH_PE_pcrel.
    ///
    /// @param[in] text_addr
    ///     The text (code) relative address to use when the encoding is
    ///     \c DW_GNU_EH_PE_textrel.
    ///
    /// @param[in] data_addr
    ///     The data relative address to use when the encoding is
    ///     \c DW_GNU_EH_PE_datarel.
    ///
    /// @return
    ///     The extracted GNU encoded pointer value.
    //------------------------------------------------------------------
    uint64_t
    GetGNUEHPointer (lldb::offset_t *offset_ptr,
                     uint32_t eh_ptr_enc,
                     lldb::addr_t pc_rel_addr,
                     lldb::addr_t text_addr,
                     lldb::addr_t data_addr);

    //------------------------------------------------------------------
    /// Extract an integer of size \a byte_size from \a *offset_ptr.
    ///
    /// Extract a single 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
    /// >= 1 and <= 4 since the return value is only 32 bits wide. Any
    /// \a byte_size values less than 1 or greater than 4 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.
    ///
    /// @return
    ///     The integer value that was extracted, or zero on failure.
    //------------------------------------------------------------------
    uint32_t
    GetMaxU32 (lldb::offset_t *offset_ptr, size_t byte_size) const;

    //------------------------------------------------------------------
    /// 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.
    ///
    /// @return
    ///     The unsigned integer value that was extracted, or zero on
    ///     failure.
    //------------------------------------------------------------------
    uint64_t
    GetMaxU64 (lldb::offset_t *offset_ptr, size_t byte_size) const;

    uint64_t
    GetMaxU64_unchecked (lldb::offset_t *offset_ptr, size_t byte_size) const;

    //------------------------------------------------------------------
    /// 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] byte_size
    ///     The size in byte of the integer to extract.
    ///
    /// @return
    ///     The sign extended signed integer value that was extracted,
    ///     or zero on failure.
    //------------------------------------------------------------------
    int64_t
    GetMaxS64 (lldb::offset_t *offset_ptr, size_t size) const;

    //------------------------------------------------------------------
    /// Extract an unsigned integer of size \a byte_size from \a
    /// *offset_ptr, then extract the bitfield from this value if
    /// \a bitfield_bit_size is non-zero.
    ///
    /// 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 8 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] bitfield_bit_size
    ///     The size in bits of the bitfield value to extract, or zero
    ///     to just extract the entire integer value.
    ///
    /// @param[in] bitfield_bit_offset
    ///     The bit offset of the bitfield value in the extracted
    ///     integer (the number of bits to shift the integer to the
    ///     right).
    ///
    /// @return
    ///     The unsigned bitfield integer value that was extracted, or
    ///     zero on failure.
    //------------------------------------------------------------------
    uint64_t
    GetMaxU64Bitfield (lldb::offset_t *offset_ptr,
                       size_t size,
                       uint32_t bitfield_bit_size,
                       uint32_t bitfield_bit_offset) const;

    //------------------------------------------------------------------
    /// Extract an signed integer of size \a byte_size from \a
    /// *offset_ptr, then extract and signe extend the bitfield from
    /// this value if \a bitfield_bit_size is non-zero.
    ///
    /// 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] byte_size
    ///     The size in bytes of the integer to extract.
    ///
    /// @param[in] bitfield_bit_size
    ///     The size in bits of the bitfield value to extract, or zero
    ///     to just extract the entire integer value.
    ///
    /// @param[in] bitfield_bit_offset
    ///     The bit offset of the bitfield value in the extracted
    ///     integer (the number of bits to shift the integer to the
    ///     right).
    ///
    /// @return
    ///     The signed bitfield integer value that was extracted, or
    ///     zero on failure.
    //------------------------------------------------------------------
    int64_t
    GetMaxS64Bitfield (lldb::offset_t *offset_ptr,
                       size_t size,
                       uint32_t bitfield_bit_size,
                       uint32_t bitfield_bit_offset) 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
    /// comes from the \a m_addr_size member variable and should 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
    GetPointer (lldb::offset_t *offset_ptr) const;

    //------------------------------------------------------------------
    /// Get the current byte order value.
    ///
    /// @return
    ///     The current byte order value from this object's internal
    ///     state.
    //------------------------------------------------------------------
    lldb::ByteOrder
    GetByteOrder() const
    {
        return m_byte_order;
    }

    //------------------------------------------------------------------
    /// 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.
    ///
    /// @return
    ///     The extracted uint8_t value.
    //------------------------------------------------------------------
    uint8_t
    GetU8 ( lldb::offset_t *offset_ptr) const;

    uint8_t
    GetU8_unchecked (lldb::offset_t *offset_ptr) const
    {
        uint8_t val = m_start[*offset_ptr];
        *offset_ptr += 1;
        return val;
    }

    uint16_t
    GetU16_unchecked (lldb::offset_t *offset_ptr) const;

    uint32_t
    GetU32_unchecked (lldb::offset_t *offset_ptr) const;

    uint64_t
    GetU64_unchecked (lldb::offset_t *offset_ptr) const;
    //------------------------------------------------------------------
    /// 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.
    //------------------------------------------------------------------
    void *
    GetU8 (lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;

    //------------------------------------------------------------------
    /// 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.
    ///
    /// @return
    ///     The extracted uint16_t value.
    //------------------------------------------------------------------
    uint16_t
    GetU16 (lldb::offset_t *offset_ptr) const;

    //------------------------------------------------------------------
    /// 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.
    //------------------------------------------------------------------
    void *
    GetU16 (lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;

    //------------------------------------------------------------------
    /// 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.
    ///
    /// @return
    ///     The extracted uint32_t value.
    //------------------------------------------------------------------
    uint32_t
    GetU32 (lldb::offset_t *offset_ptr) const;

    //------------------------------------------------------------------
    /// 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.
    //------------------------------------------------------------------
    void *
    GetU32 (lldb::offset_t *offset_ptr, void *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.
    ///
    /// @return
    ///     The extracted uint64_t value.
    //------------------------------------------------------------------
    uint64_t
    GetU64 (lldb::offset_t *offset_ptr) const;

    //------------------------------------------------------------------
    /// 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.
    //------------------------------------------------------------------
    void *
    GetU64 ( lldb::offset_t *offset_ptr, void *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] 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 signed integer value.
    //------------------------------------------------------------------
    int64_t
    GetSLEB128 (lldb::offset_t *offset_ptr) const;

    //------------------------------------------------------------------
    /// 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.
    ///
    /// @return
    ///     The extracted unsigned integer value.
    //------------------------------------------------------------------
    uint64_t
    GetULEB128 (lldb::offset_t *offset_ptr) const;

    lldb::DataBufferSP &
    GetSharedDataBuffer ()
    {
        return m_data_sp;
    }

    //------------------------------------------------------------------
    /// Peek at a C string at \a offset.
    ///
    /// Peeks at a string in the contained data. No verification is done
    /// to make sure the entire string lies within the bounds of this
    /// object's data, only \a offset is verified to be a valid offset.
    ///
    /// @param[in] offset
    ///     An offset into the data.
    ///
    /// @return
    ///     A non-NULL C string pointer if \a offset is a valid offset,
    ///     NULL otherwise.
    //------------------------------------------------------------------
    const char *
    PeekCStr (lldb::offset_t offset) const;

    //------------------------------------------------------------------
    /// Peek at a bytes at \a offset.
    ///
    /// Returns a pointer to \a length bytes at \a offset as long as
    /// there are \a length bytes available starting at \a offset.
    ///
    /// @return
    ///     A non-NULL data pointer if \a offset is a valid offset and
    ///     there are \a length bytes available at that offset, NULL
    ///     otherwise.
    //------------------------------------------------------------------
    const uint8_t*
    PeekData (lldb::offset_t offset, lldb::offset_t length) const
    {
        if (length > 0 && ValidOffsetForDataOfSize(offset, length))
            return m_start + offset;
        return NULL;
    }

    //------------------------------------------------------------------
    /// Set the address byte size.
    ///
    /// Set the size in bytes that will be used when extracting any
    /// address and pointer values from data contained in this object.
    ///
    /// @param[in] addr_size
    ///     The size in bytes to use when extracting addresses.
    //------------------------------------------------------------------
    void
    SetAddressByteSize (uint32_t addr_size)
    {
        m_addr_size = addr_size;
    }

    //------------------------------------------------------------------
    /// Set data with a buffer that is caller owned.
    ///
    /// Use data that is owned by the caller when extracting values.
    /// The data must stay around as long as this object, or any object
    /// that copies a subset of this object's data, is valid. If \a
    /// bytes is NULL, or \a length is zero, this object will contain
    /// no data.
    ///
    /// @param[in] bytes
    ///     A pointer to caller owned data.
    ///
    /// @param[in] length
    ///     The length in bytes of \a bytes.
    ///
    /// @param[in] byte_order
    ///     A byte order of the data that we are extracting from.
    ///
    /// @return
    ///     The number of bytes that this object now contains.
    //------------------------------------------------------------------
    lldb::offset_t
    SetData (const void *bytes, lldb::offset_t length, lldb::ByteOrder byte_order);

    //------------------------------------------------------------------
    /// Adopt a subset of \a data.
    ///
    /// Set this object's data to be a subset of the data bytes in \a
    /// data. If \a data contains shared data, then a reference to the
    /// shared data will be added to ensure the shared data stays around
    /// as long as any objects have references to the shared data. The
    /// byte order and the address size settings are copied from \a
    /// data. If \a offset is not a valid offset in \a data, then no
    /// reference to the shared data will be added. If there are not
    /// \a length bytes available in \a data starting at \a offset,
    /// the length will be truncated to contains as many bytes as
    /// possible.
    ///
    /// @param[in] data
    ///     Another DataExtractor object that contains data.
    ///
    /// @param[in] offset
    ///     The offset into \a data at which the subset starts.
    ///
    /// @param[in] length
    ///     The length in bytes of the subset of \a data.
    ///
    /// @return
    ///     The number of bytes that this object now contains.
    //------------------------------------------------------------------
    lldb::offset_t
    SetData (const DataExtractor& data, lldb::offset_t offset, lldb::offset_t length);

    //------------------------------------------------------------------
    /// Adopt a subset of shared data in \a data_sp.
    ///
    /// Copies the data shared pointer which adds a reference to the
    /// contained in \a data_sp. The shared data reference is reference
    /// counted to ensure the data lives as long as anyone still has a
    /// valid shared pointer to the data in \a data_sp. The byte order
    /// and address byte size settings remain the same. If
    /// \a offset is not a valid offset in \a data_sp, then no reference
    /// to the shared data will be added. If there are not \a length
    /// bytes available in \a data starting at \a offset, the length
    /// will be truncated to contains as many bytes as possible.
    ///
    /// @param[in] data_sp
    ///     A shared pointer to data.
    ///
    /// @param[in] offset
    ///     The offset into \a data_sp at which the subset starts.
    ///
    /// @param[in] length
    ///     The length in bytes of the subset of \a data_sp.
    ///
    /// @return
    ///     The number of bytes that this object now contains.
    //------------------------------------------------------------------
    lldb::offset_t
    SetData (const lldb::DataBufferSP& data_sp, lldb::offset_t offset = 0, lldb::offset_t length = LLDB_INVALID_OFFSET);

    //------------------------------------------------------------------
    /// Set the byte_order value.
    ///
    /// Sets the byte order of the data to extract. Extracted values
    /// will be swapped if necessary when decoding.
    ///
    /// @param[in] byte_order
    ///     The byte order value to use when extracting data.
    //------------------------------------------------------------------
    void
    SetByteOrder (lldb::ByteOrder byte_order)
    {
        m_byte_order = byte_order;
    }

    //------------------------------------------------------------------
    /// Skip an LEB128 number at \a *offset_ptr.
    ///
    /// Skips a LEB128 number (signed or unsigned) 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.
    ///
    /// @return
    //      The number of bytes consumed during the extraction.
    //------------------------------------------------------------------
    uint32_t
    Skip_LEB128 (lldb::offset_t *offset_ptr) const;

    //------------------------------------------------------------------
    /// 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
    ValidOffset (lldb::offset_t offset) const
    {
        return offset < GetByteSize();
    }

    //------------------------------------------------------------------
    /// 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
    ValidOffsetForDataOfSize (lldb::offset_t offset, lldb::offset_t length) const
    {
        return length <= BytesLeft (offset);
    }

    size_t
    Copy (DataExtractor& dest_data) const;

    bool
    Append (DataExtractor& rhs);

    bool
    Append (void* bytes, lldb::offset_t length);

    lldb::offset_t
    BytesLeft (lldb::offset_t offset) const
    {
        const lldb::offset_t size = GetByteSize();
        if (size > offset)
            return size - offset;
        return 0;
    }

protected:

    //------------------------------------------------------------------
    // Member variables
    //------------------------------------------------------------------
    const uint8_t * m_start;        ///< A pointer to the first byte of data.
    const uint8_t * m_end;          ///< A pointer to the byte that is past the end of the data.
    lldb::ByteOrder m_byte_order;   ///< The byte order of the data we are extracting from.
    uint32_t m_addr_size;           ///< The address size to use when extracting pointers or addresses
    mutable lldb::DataBufferSP m_data_sp; ///< The shared pointer to data that can be shared among multilple instances
};

} // namespace lldb_private

#endif  // #if defined (__cplusplus)
#endif  // #ifndef liblldb_DataExtractor_h_