bdlb_print

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

This section illustrates intended use 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());