Crate rhexdump

This crate provides a hexdump library to format data in a fast, convenient and customizable manner.

Features

Rhexdump provides the following features:

• Macros to format data and configure Rhexdump efficiently;
• Hexdump utilities ready to be used or that can be adapted to your needs;
• Iterators
• Customizable settings for Rhexdump instances.

Macros

Macros work on byte slices and can be used to format data to stdout or a string.

use rhexdump::prelude::*;

let v = (0..0x80).collect::<Vec<u8>>();

// Hexdumps `v` to stdout using the current global configuration.
rhexdump!(&v);

// 00000000: 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f | ................
// 00000010: 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f | ................
// 00000020: 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f | .!"#$%&'()*+,-./
// 00000030: 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f | 0123456789:;<=>?
// 00000040: 40 41 42 43 44 45 46 47 48 49 4a 4b 4c 4d 4e 4f | @ABCDEFGHIJKLMNO
// 00000050: 50 51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f | PQRSTUVWXYZ[\]^_
// 00000060: 60 61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f | `abcdefghijklmno
// 00000070: 70 71 72 73 74 75 76 77 78 79 7a 7b 7c 7d 7e 7f | pqrstuvwxyz{|}~.


// Hexdumps `v` to stdout with an offest using the current global configuration.
rhexdump!(&v, 0x12340000);

// 12340000: 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f | ................
// 12340010: 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f | ................
// 12340020: 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f | .!"#$%&'()*+,-./
// 12340030: 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f | 0123456789:;<=>?
// 12340040: 40 41 42 43 44 45 46 47 48 49 4a 4b 4c 4d 4e 4f | @ABCDEFGHIJKLMNO
// 12340050: 50 51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f | PQRSTUVWXYZ[\]^_
// 12340060: 60 61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f | `abcdefghijklmno
// 12340070: 70 71 72 73 74 75 76 77 78 79 7a 7b 7c 7d 7e 7f | pqrstuvwxyz{|}~.


// Returns the hexdump of `v` as a string using the current global configuration.
let output = rhexdumps!(&v);


// Returns the hexdump of `v`, with an offset, as a string using the current global
// configuration.
let output = rhexdumps!(&v, 0x12340000);

By default, a global configuration is provided to control the macros’ output format. This configuration can be changed using the rhexdump_install macro. You can find more information about configurations here.

use rhexdump::prelude::*;

// Data to format.
let v = (0..0x14).collect::<Vec<u8>>();
// Creating a new rhexdump configuration.
let config = RhexdumpBuilder::new()
    .base(Base::Oct)
    .bit_width(BitWidth::BW64)
    .group_size(GroupSize::Word)
    .groups_per_line(4)
    .config();
// Installing the configuration globally.
rhexdump_install!(config);
// Hexdump of the same data with the new configuration.
let output = rhexdumps!(&v);
assert_eq!(
    &output,
    "0000000000000000: 000400 001402 002404 003406  ........\n\
     0000000000000008: 004410 005412 006414 007416  ........\n\
     0000000000000010: 010420 011422                ....\n"
);

Hexdump Utilities

• Generic hexdump with an offset from a std::io::Read object to a std::io::Write one.

use rhexdump::prelude::*;
use std::io::prelude::*;
use std::io::*;
use std::env::temp_dir;
use std::fs::OpenOptions;

// Create a Rhexdump instance.
let rhx = Rhexdump::new();

// Create a temporary output file.
let filename = "rhx_rhexdump_hexdump_offset.test";
let mut test_file = temp_dir();
test_file.push(filename);
let mut f = OpenOptions::new()
    .write(true)
    .read(true)
    .create(true)
    .truncate(true)
    .open(test_file)
    .expect(&format!("Cannot create {}", filename));

// String to format.
let input = String::from("Lorem ipsum dolor sit amet, consectetur adipiscing elit");
let mut cur = Cursor::new(&input);

// Formatting data to the temp file.
rhx.hexdump_offset(&mut f, &mut cur, 0x12340000);

// Reading the temp file content and making sure it corresponds to the expected output.
f.seek(SeekFrom::Start(0))
    .expect(&format!("Could not seek to start of {}", filename));
let mut output = Vec::new();
f.read_to_end(&mut output)
    .expect(&format!("Cannot read from {}", filename));
assert_eq!(
    &String::from_utf8_lossy(&output),
    "12340000: 4c 6f 72 65 6d 20 69 70 73 75 6d 20 64 6f 6c 6f  Lorem.ipsum.dolo\n\
     12340010: 72 20 73 69 74 20 61 6d 65 74 2c 20 63 6f 6e 73  r.sit.amet,.cons\n\
     12340020: 65 63 74 65 74 75 72 20 61 64 69 70 69 73 63 69  ectetur.adipisci\n\
     12340030: 6e 67 20 65 6c 69 74                             ng.elit\n"
);

• Hexdump a byte slice to a String.

use rhexdump::prelude::*;

let v = (0..0x14).collect::<Vec<u8>>();
let rh = RhexdumpString::new();
let out = rh.hexdump_bytes(&v);
assert_eq!(
    &out,
    "00000000: 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f  ................\n\
     00000010: 10 11 12 13                                      ....\n"
);

• Hexdump with an offset a std::io::Read object to std::io::Stdout.

use rhexdump::prelude::*;

// Create a Rhexdump instance.
let rhx = RhexdumpStdout::new();

// String to format.
let input = String::from("Lorem ipsum dolor sit amet, consectetur adipiscing elit");
let mut cur = std::io::Cursor::new(&input);

// Formatting data to the temp file.
rhx.hexdump_offset(&mut cur, 0x12340000);

Additional hexdump methods can be found here.

Iterators

This crate also provides iterators over hexdump-formatted data.

use rhexdump::prelude::*;

// Create a Rhexdump instance.
let rhx = Rhexdump::new();

// String to format.
let input = String::from("Lorem ipsum dolor sit amet, consectetur adipiscing elit");
let mut cur = std::io::Cursor::new(&input);

// Creating an iterator.
let mut iter = RhexdumpStringIter::new(rhx, &mut cur);

// Taking two lines of output.
let _ = iter.next().unwrap();
let output = iter.next().unwrap();

assert_eq!(
    &output,
    "00000010: 72 20 73 69 74 20 61 6d 65 74 2c 20 63 6f 6e 73  r.sit.amet,.cons"
);

Customizable Settings

Use the RhexdumpBuilder object to construct a customized configuration for your data.

use rhexdump::prelude::*;

let v = (0..0x10).collect::<Vec<u8>>();
let rh = RhexdumpBuilder::new()
    .group_size(GroupSize::Dword)
    .groups_per_line(4)
    .endianness(Endianness::BigEndian)
    .build_string();
let out = rh.hexdump_bytes(&v);
assert_eq!(
    &out,
    "00000000: 00010203 04050607 08090a0b 0c0d0e0f  ................\n"
);

Modules

• builder
  Rhexdump instance builder object and methods.
• config
  Rhexdump configuration structure.
• hexdump
  Hexdump interfaces and utilities.
• iter
  Iterators over hexdump-formatted data.
• prelude
  Rhexdump prelude.

Macros

• rhexdump
  Hexdump to std::io::Stdout.
• rhexdump_install
  Installs a new thread-local global configuration RhexdumpConfig.
• rhexdumps
  Hexdump to a String.

Constants

• INSTANCE
  Global rhexdump configuration, use rhexdump_install to modify it.