std::quoted

Defined in header `<iomanip>`
template< class CharT > /unspecified/ quoted( const CharT* s, CharT delim=CharT('"'), CharT escape=CharT('\\') );	(1)	(since C++14)
template< class CharT, class Traits, class Allocator > /unspecified/ quoted( const std::basic_string<CharT, Traits, Allocator>& s, CharT delim=CharT('"'), CharT escape=CharT('\\') );	(2)	(since C++14)
template< class CharT, class Traits> /unspecified/ quoted( std::basic_string_view<CharT, Traits> s, CharT delim=CharT('"'), CharT escape=CharT('\\') );	(3)	(since C++17)
template< class CharT, class Traits, class Allocator > /unspecified/ quoted( std::basic_string<CharT, Traits, Allocator>& s, CharT delim=CharT('"'), CharT escape=CharT('\\') );	(4)	(since C++14)

Allows insertion and extraction of quoted strings, such as the ones found in CSV or XML.

When used in an expression out << quoted(s, delim, escape), where out is an output stream with char_type equal to CharT and, for overloads 2-4, traits_type equal to Traits, behaves as a FormattedOutputFunction, which inserts into out a sequence of characters seq constructed as follows:

a) First, the character delim is added to the sequence

b) Then every character from s, except if the next character to output equals delim or equals escape (as determined by the stream's traits_type::eq), then first appends an extra copy of escape

c) In the end, delim is appended to seq once more

Then, if seq.size() < out.width(), adds out.width()-seq.size() copies of the fill character out.fill() either at the end of the sequence (if ios_base::left is set in out.flags()) or at the beginning of the sequence (in all other cases).

Finally, outputs each character from the resulting sequence as if by calling out.rdbuf()->sputn(seq, n), where n=std::max(out.width(), seq.size()) and out.width(0) to cancel the effects of std::setw, if any.

4) When used in an expression in >> quoted(s, delim, escape), where in is an input stream with char_type equal to CharT and traits_type equal to Traits, extracts characters from in, using std::basic_istream::operator>>, according to the following rules:

a) If the first character extracted does not equal delim (as determined by the stream's traits_type::eq), then simply performs in >> s.

b) Otherwise (if the first character is the delimiter):

1) Turns off the skipws flag on the input stream

2) Empties the destination string by calling s.clear()

3) Extracts characters from in and appends them to s, except that whenever an escape character is extracted, it is ignored and the next character is appended to s. Extraction stops when !in == true or when an unescaped delim character is found.

4) Discards the final (unescaped) delim character.

5) Restores the skipws flag on the input stream to its original value.

Parameters

s	-	the string to insert or extract
delim	-	the character to use as the delimiter, defaults to `"`
escape	-	the character to use as the escape character, defaults to `\`

Return value

Returns an object of unspecified type such that the described behavior takes place.

Exceptions

Throws std::ios_base::failure if operator>> or operator<< throws.

Notes

Feature testing macro: __cpp_lib_quoted_string_io

Example

Run this code

#include <iostream>
#include <iomanip>
#include <sstream>
 
int main()
{
    std::stringstream ss;
    std::string in = "String with spaces, and embedded \"quotes\" too";
    std::string out;
 
    auto show = [&](const auto& what) {
        &what == &in
            ?   std::cout << "read in     [" << in << "]\n"
                          << "stored as   [" << ss.str() << "]\n"
            :   std::cout << "written out [" << out << "]\n\n";
    };
 
    ss << quoted(in); // uses ADL, so `std::` can be omitted
    show(in);
    ss >> quoted(out);
    show(out);
 
    ss.str(""); // clear the stream buffer
 
    in = "String with spaces, and embedded $quotes$ too";
    const char delim {'$'};
    const char escape {'%'};
 
    ss << std::quoted(in, delim, escape);
    show(in);
    ss >> std::quoted(out, delim, escape);
    show(out);
}

Output:

read in     [String with spaces, and embedded "quotes" too]
stored as   ["String with spaces, and embedded \"quotes\" too"]
written out [String with spaces, and embedded "quotes" too]
 
read in     [String with spaces, and embedded $quotes$ too]
stored as   [$String with spaces, and embedded %$quotes%$ too$]
written out [String with spaces, and embedded $quotes$ too]

Compiler support
Freestanding and hosted
Language
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Atomic operations library (C++11)
Thread support library (C++11)
Technical specifications
Symbols index
External libraries

I/O manipulators
C-style I/O
Buffers
basic_streambuf
basic_filebuf
basic_stringbuf
basic_spanbuf (C++23)
strstreambuf (deprecated in C++98)
basic_syncbuf (C++20)
Streams
Abstractions
ios_base
basic_ios
basic_istream
basic_ostream
basic_iostream
File I/O
basic_ifstream
basic_ofstream
basic_fstream
String I/O
basic_istringstream
basic_ostringstream
basic_stringstream
Array I/O
basic_ispanstream (C++23)
basic_ospanstream (C++23)
basic_spanstream (C++23)
istrstream (deprecated in C++98)
ostrstream (deprecated in C++98)
strstream (deprecated in C++98)
Synchronized Output
basic_osyncstream (C++20)
Types
streamoff
streamsize
fpos
Error category interface
iostream_category (C++11)
io_errc (C++11)