std::println(std::ostream)(3)

💅 std::println(std::ostream) — NAME

okay bestie, this is std::println(std::ostream), straight out of the C++ Standard Library (section 3 of the manual, iykyk). It's the "print it and then hit enter" queen of the <ostream> world. Let's get into it ✨

---

🌸 Synopsis

She lives here:

Defined in header <ostream>

The signatures, verbatim, no cap:

template< class... Args >
void println( std::ostream& os, std::format_string<Args...> fmt,
(1) (since C++23)
   Args&&... args );

void println( std::ostream& os );
(2) (since C++26)

So what does she do? She formats args according to the format string fmt, with a '\n' appended — which means that each output ends with a new-line, bestie, every single time — and then inserts the result into the os stream. 🎀

The overloads, spelled out:

1. Equivalent to: std::print(os, "{}\n", std::format(fmt, args...));
2. Equivalent to: std::print(os, "\n");

🫶 Heads up: the behavior is undefined if std::formatter<Ti, char> does not meet the BasicFormatter requirements for any Ti in Args (as required by std::make_format_args). So like... don't do that. Please. 💀

---

🦋 Parameters

• os — output stream to insert data into
• fmt — an object that represents the format string. The format string consists of:
  • ordinary characters (except { and }), which are copied unchanged to the output,
  • escape sequences {{ and }}, which are replaced with { and } respectively in the output, and
  • replacement fields.

Each replacement field has the following format:

{ arg-id (optional) }               (1)
{ arg-id (optional) : format-spec } (2)

1. replacement field without a format specification
2. replacement field with a format specification

• arg-id — specifies the index of the argument in args whose value is to be used for formatting; if it is omitted, the arguments are used in order. The arg-id s in a format string must all be present or all be omitted. Mixing manual and automatic indexing is an error 😭
• format-spec — the format specification defined by the std::formatter specialization for the corresponding argument. Cannot start with }.

Now, what that format-spec actually means depends on the type, and there's a whole little menu of vibes:

• For basic types and standard string types, the format specification is interpreted as standard format specification.
• For chrono types, the format specification is interpreted as chrono format specification.
• For range types, the format specification is interpreted as range format specification.
• For std::pair and std::tuple, the format specification is interpreted as tuple format specification.
• For std::thread::id and std::stacktrace_entry, see thread id format specification and stacktrace entry format specification. (since C++23)
• For std::basic_stacktrace, no format specifier is allowed. 🚫
• For std::filesystem::path, see path format specification. (since C++26)
• For other formattable types, the format specification is determined by user-defined formatter specializations.
• args... — arguments to be formatted 💖

---

🎀 Return value

(none)

Yeah. She gives you nothing back. She just does the thing and leaves. Main character energy honestly. 👑

---

⭐ Exceptions

• std::bad_alloc on allocation failure.
• Propagate any exception thrown by any formatter, e.g. std::format_error, without regard to the value of os.exceptions() and without turning on ios_base::badbit in the error state of os.
• May throw ios_base::failure caused by os.setstate(ios_base::badbit) which is called if an insertion into os fails.

💀 yeah the exception behavior is a whole thing — those formatter exceptions do NOT care about your stream's exception mask and will NOT flip badbit for you. Fr fr.

---

🌈 Notes

Even though overload (2) is added in C++26, all known implementations make it available in C++23 mode. Slay, we love an early release. 🫶

Feature-test macros, since tables aren't a thing here, list form:

• __cpp_lib_print — value 202207L, (C++23), feature: Formatted output
• __cpp_lib_format — value 202207L, (C++23), feature: Exposing std::basic_format_string

---

🦄 Example

This section is incomplete.

Reason: no example.

(not me showing up to a manpage with zero example 😭 it's giving "trust me bro". Anyway.)

---

💜 See also

• print(std::ostream) (C++23) — outputs formatted representation of the arguments (function template)
• println (C++23) — same as std::print except that each print is terminated by additional new line (function template)
• format (C++20) — stores formatted representation of the arguments in a new string (function template)

Also logged in the category: Todo no example. 🍓

---

✨ and that's the whole page, bestie — brought to you by http://cppreference.com, dated 2024.06.10, for std::println(std::ostream)(3). go forth and newline responsibly 💅🦋