Component bdlb_print [Package bdlb]

Provide platform-independent stream utilities. More...

Namespaces
namespace	bdlb

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  •  
    • xxd-Compatible hexDump
  • Usage
    • Example 1: Using printPtr
    • Example 2: Using the Helper Classes

Purpose:

Provide platform-independent stream utilities.

Classes:

bdlb::Print	namespace for procedures on streams
bdlb::PrintStringHexDumper	create/print hex buffers, multi-line
bdlb::PrintStringSingleLineHexDumper	create/print hex buffers, single line

Description:

This component provides a namespace, bdlb::Print, containing utility functions for formatting data to bsl::ostream objects. These functions provide several variations of hexadecimal format, allow platform-independent representation of void * pointers, and can help with the indentation of hierarchical data.

This component also provides two helper classes, bdlb::PrintStringHexDumper and bdlb::PrintStringSingleLineHexDumper, that define operator<< so they can be used in chains of << operations. The bdlb::PrintStringHexDumper class produces formatted, possibly multi-line output, whereas the bdlb::PrintStringSingleLineHexDumper class produces a simple sequence of hexadecimal digits (and no newline).

xxd-Compatible hexDump:

The output generated by the hexDump functions is not xxd-compatible (see http://gd.tuwien.ac.at/linuxcommand.org/man_pages/xxd1.html). The following perl script is provided that will convert hexDump output into xxd-compatible form. Run the script with a file containing the hexDump output as the first argument.

  #!/usr/bin/perl -w

  use strict;

  my $num = 0;
  while (<>) {
      next if (!$_);
      my $str = $_;
      next if !($str =~ s/^[^:]*?:\s*//);
      my $h = sprintf("%08X",$num);
      $str =~ s/(\S{4})([\S\W]{4})\s?([\S\W]{4})([\S\W]{4})\s?([\S\W]{4})?
            ([\S\W]{4})?\s?([\S\W]{4})?([\S\W]{4})?/$1 $2 $3 $4 $5 $6 $7 $8/;
      $str =~ s/\s \|([^|]+)\|.*$/ $1/;
      print "$h: ";
      print $str;
      $num = $num + 16;
  }

Usage:

In this section we show intended usage of this component.

Example 1: Using printPtr:

The default output produced from pointer values is non-standard across vendor platforms. The printPtr method addresses this inconsistency by always producing a consistent format for a given pointer size:

  const void *a = reinterpret_cast<void *>(0x0);
  const void *b = reinterpret_cast<void *>(0xf2ff);
  const void *c = reinterpret_cast<void *>(0x0123);
  const void *d = reinterpret_cast<void *>(0xf1f2abc9);

  bsl::ostringstream out1;

  bdlb::Print::printPtr(out1, a); out1 << endl;
  bdlb::Print::printPtr(out1, b); out1 << endl;
  bdlb::Print::printPtr(out1, c); out1 << endl;
  bdlb::Print::printPtr(out1, d); out1 << endl;

  assert("0"        "\n"
         "f2ff"     "\n"
         "123"      "\n"
         "f1f2abc9" "\n" == out1.str());

Example 2: Using the Helper Classes:

The two helper classes allow users to stream a hexadecimal representation of a sequence of bytes into an output stream.

The bdlb::PrintStringHexDumper provides a formatted, possibly multi-line representation:

  char buf[] = "abcdefghijklmnopqrstuvwxyz";

  bsl::ostringstream out2a;
  out2a << bdlb::PrintStringHexDumper(buf, sizeof buf);

  assert(
     "     0:   61626364 65666768 696A6B6C 6D6E6F70     |abcdefghijklmnop|\n"
     "    16:   71727374 75767778 797A00                |qrstuvwxyz.     |\n"
      == out2a.str());

  bsl::ostringstream out2b;
  out2b << bdlb::PrintStringSingleLineHexDumper(buf, sizeof buf);

The bdlb::PrintStringSingleLineHexDumper provides a simple, single-line representation.

  assert("6162636465666768696A6B6C6D6E6F707172737475767778797A00"
      == out2b.str());