Struct gimli::read::EndianReader

pub struct EndianReader<Endian, T> where
    Endian: Endianity,
    T: CloneStableDeref<Target = [u8]> + Debug,  { /* fields omitted */ }

An easy way to define a custom Reader implementation with a reference to a generic buffer of bytes and an associated endianity.

Note that the whole original buffer is kept alive in memory even if there is only one reader that references only a handful of bytes from that original buffer. That is, EndianReader will not do any copying, moving, or compacting in order to free up unused regions of the original buffer. If you require this kind of behavior, it is up to you to implement Reader directly by-hand.

Example

Say you have an mmaped file that you want to serve as a gimli::Reader. You can wrap that mmaped file up in a MmapFile type and use EndianReader<Rc<MmapFile>> or EndianReader<Arc<MmapFile>> as readers as long as MmapFile dereferences to the underlying [u8] data.

use std::io;
use std::ops::Deref;
use std::path::Path;
use std::slice;
use std::sync::Arc;

/// A type that represents an `mmap`ed file.
#[derive(Debug)]
pub struct MmapFile {
    ptr: *const u8,
    len: usize,
}

impl MmapFile {
    pub fn new(path: &Path) -> io::Result<MmapFile> {
        // Call `mmap` and check for errors and all that...
    }
}

impl Drop for MmapFile {
    fn drop(&mut self) {
        // Call `munmap` to clean up after ourselves...
    }
}

// And `MmapFile` can deref to a slice of the `mmap`ed region of memory.
impl Deref for MmapFile {
    type Target = [u8];
    fn deref(&self) -> &[u8] {
        unsafe {
            slice::from_raw_parts(self.ptr, self.len)
        }
    }
}

/// A type that represents a shared `mmap`ed file.
#[derive(Debug, Clone)]
pub struct ArcMmapFile(Arc<MmapFile>);

// And `ArcMmapFile` can deref to a slice of the `mmap`ed region of memory.
impl Deref for ArcMmapFile {
    type Target = [u8];
    fn deref(&self) -> &[u8] {
        &self.0
    }
}

// These are both valid for any `Rc` or `Arc`.
unsafe impl gimli::StableDeref for ArcMmapFile {}
unsafe impl gimli::CloneStableDeref for ArcMmapFile {}

/// A `gimli::Reader` that is backed by an `mmap`ed file!
pub type MmapFileReader<Endian> = gimli::EndianReader<Endian, ArcMmapFile>;

Implementations

impl<Endian, T> EndianReader<Endian, T> where
    Endian: Endianity,
    T: CloneStableDeref<Target = [u8]> + Debug, 

pub fn new(bytes: T, endian: Endian) -> EndianReader<Endian, T>

Construct a new EndianReader with the given bytes.

pub fn bytes(&self) -> &[u8]

Return a reference to the raw bytes underlying this reader.

impl<Endian, T> EndianReader<Endian, T> where
    Endian: Endianity,
    T: CloneStableDeref<Target = [u8]> + Debug, 

Range Methods

Unfortunately, std::ops::Index must return a reference, so we can't implement Index<Range<usize>> to return a new EndianReader the way we would like to. Instead, we abandon fancy indexing operators and have these plain old methods.

pub fn range(&self, idx: Range<usize>) -> EndianReader<Endian, T>

Take the given start..end range of the underlying buffer and return a new EndianReader.

use gimli::{EndianReader, LittleEndian};
use std::sync::Arc;

let buf = Arc::<[u8]>::from(&[0x01, 0x02, 0x03, 0x04][..]);
let reader = EndianReader::new(buf.clone(), LittleEndian);
assert_eq!(reader.range(1..3),
           EndianReader::new(&buf[1..3], LittleEndian));

Panics

Panics if the range is out of bounds.

pub fn range_from(&self, idx: RangeFrom<usize>) -> EndianReader<Endian, T>

Take the given start.. range of the underlying buffer and return a new EndianReader.

use gimli::{EndianReader, LittleEndian};
use std::sync::Arc;

let buf = Arc::<[u8]>::from(&[0x01, 0x02, 0x03, 0x04][..]);
let reader = EndianReader::new(buf.clone(), LittleEndian);
assert_eq!(reader.range_from(2..),
           EndianReader::new(&buf[2..], LittleEndian));

Panics

Panics if the range is out of bounds.

pub fn range_to(&self, idx: RangeTo<usize>) -> EndianReader<Endian, T>

Take the given ..end range of the underlying buffer and return a new EndianReader.

use gimli::{EndianReader, LittleEndian};
use std::sync::Arc;

let buf = Arc::<[u8]>::from(&[0x01, 0x02, 0x03, 0x04][..]);
let reader = EndianReader::new(buf.clone(), LittleEndian);
assert_eq!(reader.range_to(..3),
           EndianReader::new(&buf[..3], LittleEndian));

Panics

Panics if the range is out of bounds.

Trait Implementations

impl<Endian: Clone, T: Clone> Clone for EndianReader<Endian, T> where
    Endian: Endianity,
    T: CloneStableDeref<Target = [u8]> + Debug, 

fn clone(&self) -> EndianReader<Endian, T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Endian: Copy, T: Copy> Copy for EndianReader<Endian, T> where
    Endian: Endianity,
    T: CloneStableDeref<Target = [u8]> + Debug, 

impl<Endian: Debug, T: Debug> Debug for EndianReader<Endian, T> where
    Endian: Endianity,
    T: CloneStableDeref<Target = [u8]> + Debug, 

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<Endian, T> Deref for EndianReader<Endian, T> where
    Endian: Endianity,
    T: CloneStableDeref<Target = [u8]> + Debug, 

type Target = [u8]

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<Endian, T> Eq for EndianReader<Endian, T> where
    Endian: Endianity,
    T: CloneStableDeref<Target = [u8]> + Debug, 

impl<Endian: Hash, T: Hash> Hash for EndianReader<Endian, T> where
    Endian: Endianity,
    T: CloneStableDeref<Target = [u8]> + Debug, 

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl<Endian, T> Index<RangeFrom<usize>> for EndianReader<Endian, T> where
    Endian: Endianity,
    T: CloneStableDeref<Target = [u8]> + Debug, 

type Output = [u8]

The returned type after indexing.

fn index(&self, idx: RangeFrom<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<Endian, T> Index<usize> for EndianReader<Endian, T> where
    Endian: Endianity,
    T: CloneStableDeref<Target = [u8]> + Debug, 

type Output = u8

The returned type after indexing.

fn index(&self, idx: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<Endian, T1, T2> PartialEq<EndianReader<Endian, T2>> for EndianReader<Endian, T1> where
    Endian: Endianity,
    T1: CloneStableDeref<Target = [u8]> + Debug,
    T2: CloneStableDeref<Target = [u8]> + Debug, 

fn eq(&self, rhs: &EndianReader<Endian, T2>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Endian, T> Reader for EndianReader<Endian, T> where
    Endian: Endianity,
    T: CloneStableDeref<Target = [u8]> + Debug, 

type Endian = Endian

The endianity of bytes that are read.

type Offset = usize

The type used for offsets and lengths.

fn endian(&self) -> Endian

Return the endianity of bytes that are read.

fn len(&self) -> usize

Return the number of bytes remaining.

fn empty(&mut self)

Set the number of bytes remaining to zero.

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

Set the number of bytes remaining to the specified length.

fn offset_from(&self, base: &EndianReader<Endian, T>) -> usize

Return the offset of this reader's data relative to the start of 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<usize>

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

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

Discard the specified number of bytes.

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

Split a reader in two.

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

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

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

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

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

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

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

Read exactly buf.len() bytes into buf.

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.

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

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

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

Read an unsigned LEB128 encoded integer.

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.

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.

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.