home | help 
std::quoted(3)		       C++ Standard Libary		  std::quoted(3)

NAME
     std::quoted - std::quoted

Synopsis
	Defined in header <iomanip>
	template< class CharT >

	/*unspecified*/  quoted(  const CharT* s,			     (1)
     (since C++14)

				CharT delim = CharT('"'), CharT escape =
	CharT('\\') );
	template< class CharT, class Traits, class Allocator >

	/*unspecified*/ quoted( const std::basic_string<CharT, Traits,
	Allocator>&  s, 						     (2)
     (since C++14)

				CharT delim = CharT('"'), CharT escape =
	CharT('\\') );
	template< class CharT, class Traits>

	/*unspecified*/  quoted(  std::basic_string_view<CharT, Traits> s,   (3)
     (since C++17)

				CharT delim = CharT('"'), CharT escape =
	CharT('\\') );
	template< class CharT, class Traits, class Allocator >

	/*unspecified*/ quoted( std::basic_string<CharT, Traits,
	Allocator>&  s, 						     (4)
     (since C++14)

				CharT delim=CharT('"'), CharT
	escape=CharT('\\') );

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

XML.
	1-3) 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,3),
     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  when-
     ever 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-test macro	    Value    Std     Feature
	__cpp_lib_quoted_string_io 201304L (C++14) std::quoted

Example
     // Run this code

      #include <iomanip>
      #include <iostream>
      #include <sstream>

      void default_delimiter()
      {
	  const  std::string in = "std::quoted() quotes this string and embedded
     \"quotes\" too";
	  std::stringstream ss;
	  ss << std::quoted(in);
	  std::string out;
	  ss >> std::quoted(out);

	  std::cout << "Default delimiter case:\n"
		       "read in     [" << in << "]\n"
		       "stored as   [" << ss.str() << "]\n"
		       "written out [" << out << "]\n\n";
      }

      void custom_delimiter()
      {
	  const char delim{'$'};
	  const char escape{'%'};

	  const std::string in = "std::quoted() quotes this string and	embedded
     $quotes$ $too";
	  std::stringstream ss;
	  ss << std::quoted(in, delim, escape);
	  std::string out;
	  ss >> std::quoted(out, delim, escape);

	  std::cout << "Custom delimiter case:\n"
		       "read in     [" << in << "]\n"
		       "stored as   [" << ss.str() << "]\n"
		       "written out [" << out << "]\n\n";
      }

      int main()
      {
	  default_delimiter();
	  custom_delimiter();
      }

Output:
      Default delimiter case:
      read in	  [std::quoted() quotes this string and embedded "quotes" too]
      stored  as    ["std::quoted()  quotes  this string and embedded \"quotes\"
     too"]
      written out [std::quoted() quotes this string and embedded "quotes" too]

      Custom delimiter case:
      read in	  [std::quoted() quotes this string and embedded $quotes$ $too]
      stored as   [$std::quoted() quotes this  string  and  embedded  %$quotes%$
     %$too$]
      written out [std::quoted() quotes this string and embedded $quotes$ $too]

See also
	format	stores formatted representation of the arguments in a new string
	(C++20) (function template)

http://cppreference.com 	   2024.06.10			  std::quoted(3)
home | help