CKTIS / C++
Output stream insertion operator (`<<`)
Use `<<` to write values to an output stream or change its formatting. The operand types distinguish stream insertion from the built-in left shift.
Version: ISO C++23; implementation support may vary
Syntax
out << value;
out << first << second; // (out << first) << second
out << std::boolalpha << flag;
out << (1u << 3); // insert the result of a built-in left shift
// Conventional non-member overload in the namespace of T:
std::ostream& operator<<(std::ostream& out, const T& value);In C++23, std::cout << x is ostream insertion (<<), while 1u << 3 is a built-in bitwise left shift. The token is the same, but the operand types and operations differ. The C++ grammar makes << left-associative, so out << a << b groups as (out << a) << b regardless of the selected overload's return type. For an lvalue out of type std::ostream, the usual inserters return a std::ostream& to the same stream, letting the next insertion write to that stream. No spaces or line breaks are added automatically.
Numbers use member overloads; char and text use non-member overloads. Prefer out << x to out.operator<<(x), since the explicit member call skips non-members. Inserting a const char* requires a pointer to a valid null-terminated string. std::string and std::string_view use their length, so an embedded null does not stop output. A std::string_view does not own its data: the referenced characters must remain valid throughout insertion.
Formatting belongs to the stream. Both out << std::boolalpha and out.setf(std::ios::boolalpha) enable locale-dependent Boolean names (true and false in the classic locale). The flag stays set until cleared, for example with std::noboolalpha. By contrast, std::setw(n) sets a minimum field width that ordinary character, string and numeric inserters reset to zero after using it.
out << '\n' inserts a newline without explicitly requesting a flush. std::endl inserts a newline and calls flush(). Getting the stream back does not mean the write succeeded: check if (!out) afterward. A failure can set failbit or badbit, and the stream's exception mask can cause an exception to be thrown.
For your own type T, define a non-member operator<<(std::ostream&, const T&) in the type's namespace, not in std. Argument-dependent lookup (ADL) can find it there. Write to the stream passed in and return it by reference so the caller can chain insertions.
Examples
#include <ios>
#include <iostream>
#include <locale>
#include <ostream>
#include <string_view>
namespace report {
struct Result {
std::string_view label;
bool ok;
};
std::ostream& operator<<(std::ostream& out, const Result& result) {
return out << result.label << ": " << result.ok;
}
} // namespace report
int main() {
std::cout.imbue(std::locale::classic());
std::cout.setf(std::ios::boolalpha);
const report::Result result{std::string_view{"ABC", 2}, true};
std::cout << result << ' ' << false << '\n';
std::cout << "shift=" << (1u << 3) << '\n';
}Result
AB: true false shift=8
`report::Result` prints `AB` because the view covers only the first two characters of `ABC`. The `boolalpha` flag applies both inside the custom overload and to the following `false`. On the second line, the parentheses separate the built-in shift that produces `8` from insertion of its result.
Related lessons
- C++ · Lesson 1 · Advanced · Version: 3
- C++ · Lesson 2 · Advanced · Version: 3
- C++ · Lesson 3 · Advanced · Version: 3
- C++ · Lesson 4 · Advanced · Version: 3
- C++ · Lesson 5 · Advanced · Version: 3
- C++ · Lesson 6 · Advanced · Version: 3
- C++ · Lesson 7 · Advanced · Version: 3
- C++ · Lesson 8 · Advanced · Version: 3
- C++ · Lesson 9 · Advanced · Version: 3
- C++ · Lesson 10 · Advanced · Version: 3
- C++ · Lesson 11 · Advanced · Version: 3
- C++ · Lesson 12 · Advanced · Version: 3
- C++ · Lesson 13 · Advanced · Version: 3
- C++ · Lesson 14 · Advanced · Version: 3
- C++ · Lesson 15 · Advanced · Version: 3
- C++ · Lesson 16 · Advanced · Version: 3
- C++ · Lesson 17 · Advanced · Version: 3
- C++ · Lesson 18 · Advanced · Version: 3
- C++ · Lesson 19 · Advanced · Version: 3
- C++ · Lesson 20 · Advanced · Version: 3
- C++ · Lesson 21 · Advanced · Version: 3
- C++ · Lesson 22 · Advanced · Version: 3
- C++ · Lesson 23 · Advanced · Version: 3
- C++ · Lesson 24 · Advanced · Version: 3
- C++ · Lesson 25 · Advanced · Version: 3
- C++ · Lesson 26 · Advanced · Version: 3
- C++ · Lesson 27 · Advanced · Version: 3
- C++ · Lesson 28 · Advanced · Version: 3
- C++ · Lesson 29 · Advanced · Version: 3
- C++ · Lesson 30 · Advanced · Version: 3
- C++ · Lesson 31 · Advanced · Version: 3
- C++ · Lesson 32 · Advanced · Version: 3
- C++ · Lesson 33 · Advanced · Version: 3
- C++ · Lesson 34 · Advanced · Version: 3
- C++ · Lesson 35 · Advanced · Version: 3
- C++ · Lesson 36 · Advanced · Version: 3
- C++ · Lesson 37 · Advanced · Version: 3
- C++ · Lesson 38 · Advanced · Version: 3
- C++ · Lesson 39 · Advanced · Version: 3
- C++ · Lesson 40 · Advanced · Version: 3
- C++ · Lesson 41 · Advanced · Version: 3
- C++ · Lesson 42 · Advanced · Version: 3
- C++ · Lesson 43 · Advanced · Version: 3
- C++ · Lesson 44 · Advanced · Version: 3
- C++ · Lesson 45 · Advanced · Version: 3
- C++ · Lesson 46 · Advanced · Version: 3
- C++ · Lesson 47 · Advanced · Version: 3
- C++ · Lesson 48 · Advanced · Version: 3
- C++ · Lesson 49 · Advanced · Version: 3
- C++ · Lesson 50 · Advanced · Version: 3
- C++ · Lesson 51 · Advanced · Version: 3
- C++ · Lesson 52 · Advanced · Version: 3
- C++ · Lesson 53 · Advanced · Version: 3
- C++ · Lesson 54 · Advanced · Version: 3
- C++ · Lesson 55 · Advanced · Version: 3
- C++ · Lesson 56 · Advanced · Version: 3
- C++ · Lesson 57 · Advanced · Version: 3
- C++ · Lesson 58 · Advanced · Version: 3
- C++ · Lesson 59 · Advanced · Version: 3
- C++ · Lesson 60 · Advanced · Version: 3
Sources
- WG21 N4950 — C++23 working draft
- Formatted output functions [ostream.formatted]
- Shift operators [expr.shift]
- Operators in expressions [over.match.oper]
- Argument-dependent name lookup [basic.lookup.argdep]
- String view inserters and extractors [string.view.io]
- String inserters and extractors [string.io]
- fmtflags manipulators [fmtflags.manip]
- Standard manipulators [std.manip]
- Standard basic_ostream manipulators [ostream.manip]
- basic_ios member functions [basic.ios.members]