Trait gimli::read::Reader

pub trait Reader: Debug + Clone {
    type Endian: Endianity;
    type Offset: ReaderOffset;

    // Required methods
    fn endian(&self) -> Self::Endian;
    fn len(&self) -> Self::Offset;
    fn empty(&mut self);
    fn truncate(&mut self, len: Self::Offset) -> Result<()>;
    fn offset_from(&self, base: &Self) -> Self::Offset;
    fn offset_id(&self) -> ReaderOffsetId;
    fn lookup_offset_id(&self, id: ReaderOffsetId) -> Option<Self::Offset>;
    fn find(&self, byte: u8) -> Result<Self::Offset>;
    fn skip(&mut self, len: Self::Offset) -> Result<()>;
    fn split(&mut self, len: Self::Offset) -> Result<Self>;
    fn to_slice(&self) -> Result<Cow<'_, [u8]>>;
    fn to_string(&self) -> Result<Cow<'_, str>>;
    fn to_string_lossy(&self) -> Result<Cow<'_, str>>;
    fn read_slice(&mut self, buf: &mut [u8]) -> Result<()>;

    // Provided methods
    fn read_u8_array<A>(&mut self) -> Result<A>
       where A: Sized + Default + AsMut<[u8]> { ... }
    fn is_empty(&self) -> bool { ... }
    fn read_u8(&mut self) -> Result<u8> { ... }
    fn read_i8(&mut self) -> Result<i8> { ... }
    fn read_u16(&mut self) -> Result<u16> { ... }
    fn read_i16(&mut self) -> Result<i16> { ... }
    fn read_u32(&mut self) -> Result<u32> { ... }
    fn read_i32(&mut self) -> Result<i32> { ... }
    fn read_u64(&mut self) -> Result<u64> { ... }
    fn read_i64(&mut self) -> Result<i64> { ... }
    fn read_f32(&mut self) -> Result<f32> { ... }
    fn read_f64(&mut self) -> Result<f64> { ... }
    fn read_uint(&mut self, n: usize) -> Result<u64> { ... }
    fn read_null_terminated_slice(&mut self) -> Result<Self> { ... }
    fn skip_leb128(&mut self) -> Result<()> { ... }
    fn read_uleb128(&mut self) -> Result<u64> { ... }
    fn read_uleb128_u32(&mut self) -> Result<u32> { ... }
    fn read_uleb128_u16(&mut self) -> Result<u16> { ... }
    fn read_sleb128(&mut self) -> Result<i64> { ... }
    fn read_initial_length(&mut self) -> Result<(Self::Offset, Format)> { ... }
    fn read_address(&mut self, address_size: u8) -> Result<u64> { ... }
    fn read_word(&mut self, format: Format) -> Result<Self::Offset> { ... }
    fn read_length(&mut self, format: Format) -> Result<Self::Offset> { ... }
    fn read_offset(&mut self, format: Format) -> Result<Self::Offset> { ... }
    fn read_sized_offset(&mut self, size: u8) -> Result<Self::Offset> { ... }
}

A trait for reading the data from a DWARF section.

All read operations advance the section offset of the reader unless specified otherwise.

Choosing a Reader Implementation

gimli comes with a few different Reader implementations and lets you choose the one that is right for your use case. A Reader is essentially a view into the raw bytes that make up some DWARF, but this view might borrow the underlying data or use reference counting ownership, and it might be thread safe or not.

Implementation	Ownership	Thread Safe	Notes
EndianSlice	Borrowed	Yes	Fastest, but requires that all of your code work with borrows.
EndianRcSlice	Reference counted	No	Shared ownership via reference counting, which alleviates the borrow restrictions of EndianSlice but imposes reference counting increments and decrements. Cannot be sent across threads, because the reference count is not atomic.
EndianArcSlice	Reference counted	Yes	The same as EndianRcSlice, but uses atomic reference counting, and therefore reference counting operations are slower but EndianArcSlices may be sent across threads.
EndianReader<T>	Same as T	Same as T	Escape hatch for easily defining your own type of Reader.

Required Associated Types

type Endian: Endianity

The endianity of bytes that are read.

type Offset: ReaderOffset

The type used for offsets and lengths.

Required Methods

fn endian(&self) -> Self::Endian

Return the endianity of bytes that are read.

fn len(&self) -> Self::Offset

Return the number of bytes remaining.

fn empty(&mut self)

Set the number of bytes remaining to zero.

fn truncate(&mut self, len: Self::Offset) -> Result<()>

Set the number of bytes remaining to the specified length.

fn offset_from(&self, base: &Self) -> Self::Offset

Return the offset of this reader’s data relative to the start of the given base reader’s data.

May panic if this reader’s data is not contained within the given base reader’s data.

fn offset_id(&self) -> ReaderOffsetId

Return an identifier for the current reader offset.

fn lookup_offset_id(&self, id: ReaderOffsetId) -> Option<Self::Offset>

Return the offset corresponding to the given id if it is associated with this reader.

fn find(&self, byte: u8) -> Result<Self::Offset>

Find the index of the first occurrence of the given byte. The offset of the reader is not changed.

fn skip(&mut self, len: Self::Offset) -> Result<()>

Discard the specified number of bytes.

fn split(&mut self, len: Self::Offset) -> Result<Self>

Split a reader in two.

A new reader is returned that can be used to read the next len bytes, and self is advanced so that it reads the remainder.

fn to_slice(&self) -> Result<Cow<'_, [u8]>>

Return all remaining data as a clone-on-write slice.

The slice will be borrowed where possible, but some readers may always return an owned vector.

Does not advance the reader.

fn to_string(&self) -> Result<Cow<'_, str>>

Convert all remaining data to a clone-on-write string.

The string will be borrowed where possible, but some readers may always return an owned string.

Does not advance the reader.

Returns an error if the data contains invalid characters.

fn to_string_lossy(&self) -> Result<Cow<'_, str>>

Convert all remaining data to a clone-on-write string, including invalid characters.

The string will be borrowed where possible, but some readers may always return an owned string.

Does not advance the reader.

fn read_slice(&mut self, buf: &mut [u8]) -> Result<()>

Read exactly buf.len() bytes into buf.

Provided Methods

fn read_u8_array<A>(&mut self) -> Result<A>

where A: Sized + Default + AsMut<[u8]>,

Read a u8 array.

fn is_empty(&self) -> bool

Return true if the number of bytes remaining is zero.

fn read_u8(&mut self) -> Result<u8>

Read a u8.

fn read_i8(&mut self) -> Result<i8>

Read an i8.

fn read_u16(&mut self) -> Result<u16>

Read a u16.

fn read_i16(&mut self) -> Result<i16>

Read an i16.

fn read_u32(&mut self) -> Result<u32>

Read a u32.

fn read_i32(&mut self) -> Result<i32>

Read an i32.

fn read_u64(&mut self) -> Result<u64>

Read a u64.

fn read_i64(&mut self) -> Result<i64>

Read an i64.

fn read_f32(&mut self) -> Result<f32>

Read a f32.

fn read_f64(&mut self) -> Result<f64>

Read a f64.

fn read_uint(&mut self, n: usize) -> Result<u64>

Read an unsigned n-bytes integer u64.

Panics

Panics when nbytes < 1 or nbytes > 8

fn read_null_terminated_slice(&mut self) -> Result<Self>

Read a null-terminated slice, and return it (excluding the null).

fn skip_leb128(&mut self) -> Result<()>

Skip a LEB128 encoded integer.

fn read_uleb128(&mut self) -> Result<u64>

Read an unsigned LEB128 encoded integer.

fn read_uleb128_u32(&mut self) -> Result<u32>

Read an unsigned LEB128 encoded u32.

fn read_uleb128_u16(&mut self) -> Result<u16>

Read an unsigned LEB128 encoded u16.

fn read_sleb128(&mut self) -> Result<i64>

Read a signed LEB128 encoded integer.

fn read_initial_length(&mut self) -> Result<(Self::Offset, Format)>

Read an initial length field.

This field is encoded as either a 32-bit length or a 64-bit length, and the returned Format indicates which.

fn read_address(&mut self, address_size: u8) -> Result<u64>

Read an address-sized integer, and return it as a u64.

fn read_word(&mut self, format: Format) -> Result<Self::Offset>

Parse a word-sized integer according to the DWARF format.

These are always used to encode section offsets or lengths, and so have a type of Self::Offset.

fn read_length(&mut self, format: Format) -> Result<Self::Offset>

Parse a word-sized section length according to the DWARF format.

fn read_offset(&mut self, format: Format) -> Result<Self::Offset>

Parse a word-sized section offset according to the DWARF format.

fn read_sized_offset(&mut self, size: u8) -> Result<Self::Offset>

Parse a section offset of the given size.

This is used for DW_FORM_ref_addr values in DWARF version 2.

Object Safety

This trait is not object safe.

Implementors

impl<'input, Endian> Reader for EndianSlice<'input, Endian>

where Endian: Endianity,

type Endian = Endian

type Offset = usize