hexdump.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 Jarosław Pelczar <jarek@jpelczar.com>
//
// SPDX-License-Identifier: BSD-2-Clause
 
#pragma once
 
#include "../microfmt.hpp"
#include <algorithm>
#include <cstddef>
#include <cstdint>
#include <string_view>
 
namespace microfmt {
 
// ============================================================================
// Checked Memory Reader Callback Definition
// ============================================================================
 
using memory_reader_fn_t = size_t (*)(void *ctx, uintptr_t src_addr, uint8_t *dst_buf, size_t max_len) noexcept;
 
// ============================================================================
// Hex Dump Configuration & Descriptor
// ============================================================================
 
struct MICROFMT_API_CLASS RELOCO_POINTER hexdump_view {
  uintptr_t base_addr{0};
  span<const uint8_t> direct_data{};
  void *reader_ctx{nullptr};
  memory_reader_fn_t reader_fn{nullptr};
  size_t total_len{0};
  uint8_t bytes_per_line{16};
  bool show_ascii{true};
  bool show_address{true};
  bool uppercase{false};
};
 
[[nodiscard]] constexpr hexdump_view hexdump(span<const uint8_t> data, uintptr_t base_addr = 0,
                                             uint8_t bytes_per_line = 16, bool show_ascii = true) noexcept {
  return hexdump_view{base_addr,  data,        nullptr,
                      nullptr,    data.size(), bytes_per_line == 0 ? static_cast<uint8_t>(16) : bytes_per_line,
                      show_ascii, true,        false};
}
 
// low-level formatting: raw character pointers and integer width conversions bounded by the buffer sizes checked here.
RELOCO_BEGIN_UNSAFE_CODE
[[nodiscard]] constexpr hexdump_view hexdump_checked(uintptr_t base_addr, size_t total_len, memory_reader_fn_t reader,
                                                     void *ctx = nullptr, uint8_t bytes_per_line = 16,
                                                     bool show_ascii = true) noexcept {
  return hexdump_view{base_addr,  {},        ctx,
                      reader,     total_len, bytes_per_line == 0 ? static_cast<uint8_t>(16) : bytes_per_line,
                      show_ascii, true,      false};
}
RELOCO_END_UNSAFE_CODE
 
// ============================================================================
// Formatter Specialization for hexdump_view
// ============================================================================
 
MICROFMT_API void format_hexdump(const hexdump_view &h, span<uint8_t> line_buffer, const sink &out) noexcept;
 
#if MICROFMT_SHARED_PROVIDE_DEFINITIONS
#include "hexdump.ipp"
#endif
 
template <> struct formatter<hexdump_view> {
  constexpr void parse(format_parse_context &ctx) noexcept { (void)ctx; }
 
  void format(const hexdump_view &h, const sink &out) const noexcept {
    // NOLINTNEXTLINE(reloco-no-c-array): fixed-size buffer/table for span APIs
    uint8_t line_buffer[32] = {}; // Bounded scratch buffer on stack
    format_hexdump(h, {line_buffer, sizeof(line_buffer)}, out);
  }
};
 
inline void hexdump_to(const sink &out, span<const uint8_t> data, uintptr_t base_address = 0) noexcept {
  const formatter<hexdump_view> f = {};
  f.format(hexdump(data, base_address), out);
}
 
} // namespace microfmt