function template

std::operator<< (basic_string)

template <class charT, class traits, class Alloc>  basic_ostream<charT,traits>& operator<< (basic_ostream<charT,traits>& os,                                           const basic_string<charT,traits,Alloc>& str);

Insert string into stream

Inserts the sequence of characters that conforms value of str into os.

This function overloads

operator<< to behave as described in basic_ostream::operator<< for c-strings, but applied to basic_string objects.

Parameters

os: basic_ostream object where characters are inserted.
str: basic_string object with the content to insert.

Return Value

The same as parameter os.

If some error happens during the output operation, the stream's badbit flag is set, and if the appropriate flag has been set with basic_ios::exceptions, an exception is thrown.

Example

// inserting strings into output streams
#include <iostream>
#include <string>

main ()
{
  std::string str = "Hello world!";
  std::cout << str << '\n';
  return 0;
}

Complexity

Unspecified, but generally linear in str's length.

Iterator validity

No changes.

Data races

Objects os is modified.

Exception safety

Basic guarantee: if an exception is thrown, both is and str end up in a valid state.