bslfmt_padutil

Detailed Description

Provide padding utilities for the bslfmt package and clients.

Outline

• Purpose
• Classes
• Description
  • Usage

Purpose

Provide padding utilities for the bslfmt package and clients.

Classes

• bslfmt::PadUtil: formatter padding utilities

Description

PadUtil is a struct that serves as a namespace containing functions suitable for padding output. It consists of 2 functions, computePadding which computes the amount of left and right padding, and pad, which repeatedly outputs a sequence to an iterator.

Usage

Suppose we have a string and we want to be able to pad it with any desired filler string, and pad it to the left or right, or pad it on both sides, to reach a desired total width.

First, we define a couple of typedef's to shorten some bslfmt package types:

 typedef bslfmt::FormatterSpecificationNumericValue     NumericValue;
 typedef bslfmt::FormatSpecificationParserEnums         ParserEnums;
 typedef bslfmt::PadUtil<char>                          PadUtil;

Then, we are now able to define a function paddedString which will take a a string, content, and pad it to a given fieldWidth with the specified filler. pad does not assume that filler is a single Unicode code point, though that will normally be the case.

 void paddedString(bsl::string             *result,
                   const bsl::string_view&  content,
                   unsigned                 fieldWidth,
                   ParserEnums::Alignment   alignment,
                   const bsl::string_view&  filler)
 {
     std::ptrdiff_t leftPadding, rightPadding;
 
     PadUtil::computePadding(&leftPadding,
                             &rightPadding,
                             NumericValue(NumericValue::e_VALUE,
                                          fieldWidth),
                             content.length(),
                             alignment,
                             ParserEnums::e_ALIGN_LEFT);
 
     result->resize(filler.length() * (leftPadding + rightPadding) +
                                                          content.length());
 
     bsl::string::iterator it = result->begin();
     it = PadUtil::pad(it, leftPadding,  filler);
 
     it = bsl::copy(content.begin(), content.end(), it);
 
     it = PadUtil::pad(it, rightPadding, filler);
 
     assert(result->end() == it);
 }

Next, we use our new paddedString to create a string with "John Brown" padded on either side to a total width of 20 bytes, padding with dashes:

 bsl::string s;
 paddedString(&s, "John Brown", 20, ParserEnums::e_ALIGN_MIDDLE, "-");
 assert("-----John Brown-----" == s);

Now, let's pad to right with Unicode Euro symbols to a total width of 20 bytes:

 const char *euro = "\xe2\x82\xac";        // Unicode for the Euro symbol.
 paddedString(&s, "Seven Euros: ", 20, ParserEnums::e_ALIGN_LEFT, euro);
 assert("Seven Euros: €€€€€€€" == s);

Note that because euro is not a single byte, the output is longer than fieldWidth, which was 20:

 assert(34 == s.length());