API reference#

pw_hex_dump: Handy hexdump utilities

Core Classes#

FormattedHexDumper#

class FormattedHexDumper#

The formatted hex dumper is a configurable class that can dump hex in various formats. The default produced output is xxd compatible, though there are options to further adjust the output. One example is address prefixing, where base memory address of each line is used instead of an offset.

It is strongly recommended NOT to directly depend on this dump format; pw_hex_dump does NOT guarantee stability for the output format, but strives to remain xxd compatible.

Default: 

Offs.  0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F  Text
0000: A4 CC 32 62 9B 46 38 1A 23 1A 2A 7A BC E2 40 A0  ..2b.F8.#.*z..@.
0010: FF 33 E5 2B 9E 9F 6B 3C BE 9B 89 3C 7E 4A 7A 48  .3.+..k<...<~JzH
0020: 18                                               .

Example 1: (32-bit machine, group_every=4, prefix_mode=kAbsolute, bytes_per_line = 8) 

Address      0        4        Text
0x20000000: A4CC3262 9B46381A  ..2b.F8.
0x20000008: 231A2A7A BCE240A0  #.*z..@.
0x20000010: FF33E52B 9E9F6B3C  .3.+..k<
0x20000018: BE9B893C 7E4A7A48  ...<~JzH
0x20000020: 18                 .

Example 2: (group_every=1, bytes_per_line = 16) 

Offs.  0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
0000: A4 CC 32 62 9B 46 38 1A 23 1A 2A 7A BC E2 40 A0
0010: FF 33 E5 2B 9E 9F 6B 3C BE 9B 89 3C 7E 4A 7A 48
0020: 18

Example 3: (group_every=0, prefix_mode=kNone, show_header=false, show_ascii=false) 

A4CC32629B46381A231A2A7ABCE240A0
FF33E52B9E9F6B3CBE9B893C7E4A7A48
18

Public Functions

Status SetLineBuffer(span<char> dest)#

Set the destination buffer that the hex dumper will write to line-by-line.

Returns:

Code

Description

RESOURCE_EXHAUSTED

The buffer was set, but is too small to fit the current formatting configuration.

INVALID_ARGUMENT

The destination buffer is invalid (nullptr or zero- length).

Status BeginDump(ConstByteSpan data)#

Begin dumping the provided data. Does NOT populate the line buffer with a string, simply resets the statefulness to track this buffer.

Returns:

Code

Description

OK

Ready to begin dump.

INVALID_ARGUMENT

The source data starts at null, but has been set.

FAILED_PRECONDITION

Line buffer too small to hold current formatting settings.

Status DumpLine()#

Dumps a single line to the line buffer.

Example usage:

std::array<char, 80> temp;
FormattedHexDumper hex_dumper(temp);
hex_dumper.BeginDump(my_data);
while(hex_dumper.DumpLine().ok()) {
  LOG_INFO("%s", temp.data());
}
Returns:

Code

Description

OK

A line has been written to the line buffer.

RESOURCE_EXHAUSTED

All the data has been dumped.

FAILED_PRECONDITION

Destination line buffer is too small to fit current formatting configuration.

struct Flags#

Public Members

uint8_t bytes_per_line#

Sets the number of source data bytes to print in each formatted line.

uint8_t group_every#

Inserts a space every N bytes for readability. Note that this is in number of bytes converted to characters. Set to zero to disable.

i.e. a value of 2 results in: 

0x00000000: 0102 0304 0506 0708

bool show_ascii#

Show or hide ascii interpretation of binary data.

bool show_header#

Show descriptive column headers.

AddressMode prefix_mode#

Prefix each line of the dump with an offset or absolute address.

Utility Functions#

DumpAddr#

inline Status pw::dump::DumpAddr(span<char> dest, const void *ptr)#
Status pw::dump::DumpAddr(span<char> dest, uintptr_t addr)#

Dumps a uintptr_t to a character buffer as a hex address. This may be useful to print out an address in a generalized way when z and p aren’t supported by a standard library implementation. The destination buffer MUST be large enough to hold kHexAddrStringSize + 1 (null terminator) bytes.

Example (64-bit): 

0x000000000022b698

Example (32-bit): 

0x70000000

Returns:

Code

Description

OK

Address has been written to the buffer.

INVALID_ARGUMENT

The destination buffer is invalid (nullptr).

RESOURCE_EXHAUSTED

The destination buffer is too small. No data written.

LogBytes#

template<std::size_t kBytesPerLine = 16>
inline void pw::dump::LogBytes(int log_level, pw::ConstByteSpan bytes)#

Helper to log human-readable hex dumps to console.

Example:

std::array<const std::byte, 9> my_data = {
  std::byte('h'),
  std::byte('e'),
  std::byte('l'),
  std::byte('l'),
  std::byte('o'),
  std::byte(0xde),
  std::byte(0xad),
  std::byte(0xbe),
  std::byte(0xef),
};

LogBytes(PW_LOG_LEVEL_DEBUG, my_data);

DBG  0000: 68 65 6c 6c 6f de ad be ef                       hello....

To print other data types, obtain a ConstByteSpan view first:

LogBytes(PW_LOG_LEVEL_DEBUG, pw::as_bytes(pw::span("world!")));

DBG  0000: 77 6f 72 6c 64 21 00                             world!.

Use template arguments to modify the number of bytes printed per line:

LogBytes<8>(PW_LOG_LEVEL_DEBUG, pw::as_bytes(pw::span("hello world!")));

DBG  0000: 68 65 6c 6c 6f 20 77 6f  hello wo
DBG  0008: 72 6c 64 21 00           rld!.
Template Parameters:

kBytesPerLine – The number of input bytes to display per line. Defaults to 16.

Parameters:

  • log_level – [in] The PW_LOG_LEVEL to log at.

  • bytes – [in] The data to log.

On this page