Boost C++ Libraries

Modifiable sequences of characters are represented using objects of type string. The interface and functionality of string is the same as std::basic_string except that:

With augmented interface, operations requiring an input string are implemented as a single overload with a parameter of type string_view, and can accept most string-like objects. Objects such as null terminated character pointers, std::string, json::string, subranges of strings, and objects convertible to string_view can all be passed to these functions.

json::string str = "Boost.JSON";
json::string_view sv = str;

// all of these call compare(string_view)
str.compare(sv);

str.compare(sv.substr(0, 5));

str.compare(str);

str.compare("Boost");

More formally, std::string member function overloads that accept any of the following parameter combinations as an input string:

are replaced with with an overload accepting a string_view parameter.

This design removes several redundant overloads from the interface. For example, the 11 overloads of std::string::insert are reduced to just 3 in string, while still providing identical functionality. In addition to these changes, overloads taking a std::initializer_list<char> parameter have been removed. Such overloads have little use, as they serve as little more than a wrappers for arrays with an inefficient syntax:

std::string sstr = "hello";

json::string jstr = "hello";

assert(sstr.append({'w', 'o', 'r', 'l', 'd'}) == "helloworld");

// such syntax is inefficient, and the same can
// be achieved with a character array.

assert(jstr.append("world") == "helloworld");

With the removal of overloads that specify parameters for a substring, a member function subview that returns a string_view is provided to facilitate cheap substring operations:

std::string sstr1 = "helloworld";
std::string sstr2 = "world";

json::string jstr1 = "helloworld";
json::string jstr2 = "world";

assert( jstr2.insert(0, jstr1.subview(0, 5)) == "helloworld" );

// this is equivalent to
assert( sstr2.insert(0, sstr1, 0, 5) == "helloworld" );

A string may be constructed using the default memory resource without incurring any memory allocations. Alternatively, a storage_ptr can be provided explicitly:

string str1; // empty string, uses the default memory resource

string str2( make_shared_resource<monotonic_resource>() ); // empty string, uses a counted monotonic resource

Formatted Output

When a string is formatted to a std::ostream, the result is a valid JSON. That is, the result will be double quoted and the contents properly escaped per the JSON specification.