1//// 2Copyright 2019 Glen Joseph Fernandes 3(glenjofe@gmail.com) 4 5Distributed under the Boost Software License, Version 1.0. 6(http://www.boost.org/LICENSE_1_0.txt) 7//// 8 9# Quoted Manipulators, <boost/io/quoted.hpp> 10:toc: 11:toc-title: 12:idprefix: 13 14## Introduction 15 16C++ Standard library stream I/O for strings that contain embedded spaces can 17produce unexpected results. For example, 18 19``` 20std::stringstream ss; 21std::string original = "fooled you"; 22std::string roundtrip; 23 24ss << original; 25ss >> roundtrip; 26 27std::cout << original; // outputs: fooled you 28std::cout << roundtrip; // outputs: fooled 29 30assert(original == roundtrip); // assert will fire 31``` 32 33The Boost quoted stream I/O manipulator places delimiters, defaulted to the 34double-quote ("), around strings on output, and strips off the delimiters on 35input. This ensures strings with embedded spaces round-trip as desired. For 36example, 37 38``` 39std::stringstream ss; 40std::string original = "fooled you"; 41std::string roundtrip; 42 43ss << quoted(original); 44ss >> quoted(roundtrip); 45 46std::cout << quoted(original); // outputs: "fooled you" 47std::cout << roundtrip; // outputs: fooled you 48 49assert(original == roundtrip); // assert will not fire 50``` 51 52If the string contains the delimiter character, on output that character will 53be preceded by an escape character, as will the escape character itself: 54 55``` 56std::cout << quoted("'Jack & Jill'", '&', '\''); // outputs: '&'Jack && Jill&'' 57``` 58 59## Header synopsis 60 61[subs=+quotes] 62``` 63namespace boost { 64namespace io { 65 66template<class Char, class Traits, class Alloc> 67`unspecified-type1` 68quoted(const std::basic_string<Char, Traits, Alloc>& string, 69 Char escape='\\', Char delim='\"'); 70 71template<class Char> 72`unspecified-type2` 73quoted(const Char* string, Char escape='\\', Char delim='\"'); 74 75template<class Char, class Traits, class Alloc> 76`unspecified-type3` 77quoted(std::basic_string<Char, Traits, Alloc>& string, 78 Char escape='\\', Char delim='\"'); 79 80} // io 81} // boost 82``` 83 84*unspecified-type1*, *unspecified-type2*, and *unspecified-type3* are 85implementation supplied types with implementation supplied `operator<<`: 86 87[subs=+quotes] 88``` 89template<class Char, class Traits> 90std::basic_ostream<Char, Traits>& 91operator<<(std::basic_ostream<Char, Traits>& os, 92 const `unspecified-typeN`& proxy); 93``` 94 95Effects:: Inserts characters into `os`: 96* `delim` 97* Each character in `string`. If the character to be output is equal to 98`escape` or `delim`, as determined by `operator==`, first output `escape`. 99* `delim` 100Remarks:: `string`, `escape`, and `delim` have the type and value of the 101corresponding arguments of the call to the `quoted` function that constructed 102`proxy`. 103Returns:: `os`. 104 105*unspecified-type3* is an implementation supplied type with an implementation 106supplied `operator>>`: 107 108[subs=+quotes] 109``` 110template<class Char, class Traits> 111std::basic_istream<Char, Traits>& 112operator>>(std::basic_istream<Char, Traits>& is, 113 const `unspecified-type3`& proxy); 114``` 115 116Effects:: Extracts characters from `os`: 117* If the first character extracted is equal to `delim`, as determined by 118`operator==`, then: 119** Turn off the `skipws` flag. 120** `string.clear()` 121** Until an unescaped `delim` character is reached or `is.not_good()`, extract 122characters from `os` and append them to string, except that if an escape is 123reached, ignore it and append the next character to string. 124** Discard the final `delim` character. 125** Restore the `skipws` flag to its original value. 126* Otherwise, `os >> string`. 127 128Remarks:: `string`, `escape`, and `delim` have the type and value of the 129corresponding arguments of the call to the `quoted` function that constructed 130`proxy`. 131Returns:: `is`. 132 133## Acknowledgements 134 135The `quoted()` stream manipulator emerged from discussions on the Boost 136developers mailing list. Participants included Beman Dawes, Rob Stewart, 137Alexander Lamaison, Eric Niebler, Vicente Botet, Andrey Semashev, 138Phil Richards, and Rob Murray. Eric Niebler's suggestions provided the basis 139for the name and form of the templates. 140 141Beman Dawes started the implementation of `quoted()` as a private detail 142header. Glen Fernandes updated the implementation and also made it public. 143 144Glen Fernandes corrected the implementation to properly account for stream 145width and fill, and optimized it to write directly to the stream buffer. 146