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
The buffer was set, but is too small to fit the current formatting configuration.
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
Ready to begin dump.
The source data starts at null, but has been set.
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
A line has been written to the line buffer.
All the data has been dumped.
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.
-
uint8_t bytes_per_line#
-
Status SetLineBuffer(span<char> dest)#
Utility Functions#
DumpAddr#
-
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 whenz
andp
arenβt supported by a standard library implementation. The destination buffer MUST be large enough to holdkHexAddrStringSize + 1 (null terminator)
bytes.Example (64-bit):
0x000000000022b698
Example (32-bit):
0x70000000
- Returns:
Code
Description
Address has been written to the buffer.
The destination buffer is invalid (nullptr).
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.