Component bdlb_indexspanstringutil [Package bdlb]

Provide functions that operate on IndexSpan and string objects. More...

Namespaces
namespace	bdlb

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Creating IndexSpan Objects Safely
    • Example 2: Creating String Views

Purpose:

Provide functions that operate on IndexSpan and string objects.

Classes:

bdlb::IndexSpanStringUtil

namespace for methods on IndexSpan and strings

See also:

Component bdlb_indexspan

Description:

This component provides a struct, IndexSpanStringUtil, that serves as a namespace for utility functions that operate on IndexSpan and string objects. This component is designed to work on several representations of strings, including bsl::string, bsl::string_view, and it is also backwards compatible with bslstl::StringRef. Key operations of this utility include bind, for creating a bsl::string_view from an IndexSpan and a string, and the create methods that provide a way to create IndexSpan objects of a string object (of any kind) using positions defined by iterators and/or positions and/or length.

Usage:

This section illustrates intended use of this component.

Example 1: Creating IndexSpan Objects Safely:

Suppose that we are creating a parser, and we want the results of the parsing to be stored in IndexSpan objects. The parser will have either a pointer (or "begin" iterator) into the original string input and then another pointer (or iterator) or a length to identify the end of the input. Turning the beginning and ending identifiers into an IndexSpan is a simple calculation, but one that is verbose and potentially error prone. Instead of implementing the calculation ourselves we use the convenience function create from IndexSpanStringUtil.

First, we define a string that we want to parse:

  const bsl::string full("James Tiberius Kirk");

Then, we implement the parsing of the first name:

  typedef bsl::string::const_iterator Cit;
  Cit it = bsl::find(full.begin(), full.end(), ' ');
  // Error checking omitted since we know the string
  bdlb::IndexSpan first = bdlb::IndexSpanStringUtil::create(full,
                                                            full.begin(),
                                                            it);

Next, we implement the parsing of the middle name, this time using length, rather than an end iterator (demonstrating an alternative create overload provided by IndexSpanStringUtil):

  ++it;  // Skip the space
  Cit it2 = bsl::find(it, full.end(), ' ');
  bdlb::IndexSpan middle;
  if (full.end() != it2) {
      middle = bdlb::IndexSpanStringUtil::create(full, it, it2 - it);
      it = it2 + 1;
  }

Then, we create the IndexSpan for the last name, using two positions:

  bdlb::IndexSpan last = bdlb::IndexSpanStringUtil::createFromPositions(
                                                           full,
                                                           it - full.begin(),
                                                           full.length());

Finally, we verify that the resulting IndexSpan objects correctly describe the parsed names of the full name:

  assert(full.substr(first.position(), first.length()) == "James");

  assert(full.substr(middle.position(), middle.length()) == "Tiberius");

  assert(full.substr(last.position(), last.length()) == "Kirk");

Example 2: Creating String Views:

Suppose that we have IndexSpan objects that define the first, middle, and last part of a string that has a full name in it and we want to get actual string views that correspond to those parts of the string. The bind functions of IndexSpanStringUtil provide that functionality. The bind functions return a bsl::string_view into the original string (so the characters of the string are not copied). Note that this example builds on Example 1.

First, we define a string view of the parsed string to show that bind works both on strings and string views:

  const bsl::string_view fullView(full);

Then we demonstrate binding IndexSpan object to that view:

  assert(bdlb::IndexSpanStringUtil::bind(fullView, first) == "James");

  assert(bdlb::IndexSpanStringUtil::bind(fullView, middle) == "Tiberius");

  assert(bdlb::IndexSpanStringUtil::bind(fullView, last) == "Kirk");

Finally we demonstrate binding IndexSpan object to a bsl::string:

  assert(bdlb::IndexSpanStringUtil::bind(full, first) == "James");

  assert(bdlb::IndexSpanStringUtil::bind(full, middle) == "Tiberius");

  assert(bdlb::IndexSpanStringUtil::bind(full, last) == "Kirk");